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.
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:
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.