Skip to content
Verified

Errors

What a negative code means, and how it maps to the HTTP status you actually see.

Every method answers { code, data }. code > 0 is success. code < 0 is an error, and data is almost always a human-readable message you can show or log directly.

The HTTP status you see is not the whole story

CPI maps a negative code to an HTTP status with one rule: a code from -400 to -499 becomes that exact status (-404 answers HTTP 404, -409 answers HTTP 409, -428 answers HTTP 428). Every other negative code, -1, -500, -762, -999, anything outside that one band, answers a plain HTTP 400. The real detail always lives in the JSON body, so branch on code, never on the HTTP status alone. A -1 and a -999 look identical at the HTTP layer and very different in the body.

json
{ "code": -1, "data": "account_not_found" }

Codes worth branching on

Beyond this table, individual microservices use their own small negative codes for module-specific states (account and billing codes in the -90s, drive conflicts around -762/-764, database codes around -450/-460, and more). They are always paired with a descriptive data message, read that message and the method you called rather than the number alone.

MCP-layer errors

A request that fails before any method runs, a bad or missing key, a malformed MCP message, answers a JSON-RPC error instead of the { code, data } envelope:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

See MCP. Once a tool call actually reaches a method, its result carries the normal { code, data } envelope inside the MCP response, same as a plain REST call.

Next