skip to content

How does a JSON-RPC 2.0 server choose among the reserved error codes, and when must the error response's id be null?

level: middleimportance: must knowfreq 26%

answer

  1. five named codes, one reserved band
  2. parse, then shape, then method, then arguments
  3. a range kept for the server software
  4. application errors live outside the band
  5. null when the id is unreadable

basics

~20 s

JSON-RPC 2.0 reserves -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32602 (invalid params) and -32603 (internal error), with -32000 to -32099 for implementation-defined server errors. The id is null when it could not be determined.

solid answer

~50 s

The `error` member is an Object with an integer `code`, a short `message` and an optional `data`. The code follows how far the server got: -32700 Parse error when the text is not valid JSON; -32600 Invalid Request when it is JSON but not a valid Request object, such as a numeric `method`; -32601 Method not found; -32602 Invalid params when the method exists but the arguments do not fit; -32603 Internal error for an internal JSON-RPC failure. The whole band -32768 to -32000 is reserved — -32000 to -32099 for implementation-defined server errors, the undefined rest for future use — and the remainder of the integer space is for application-defined errors such as a refused transfer. The `id` MUST be `null` when the server could not determine it, as after a parse error or an invalid request.

go deeper

for a junior

Recall the five named codes and what each one means, and that an error response still carries jsonrpc and id but no result.

for a middle

Explain the stage order that picks a code, the reserved band and its server-error range, and why the id becomes null after a parse error or invalid request.

for a senior

Design an API's own error codes outside the reserved band, decide what belongs in message versus data, and explain how a client should handle a null-id error it cannot correlate.

for a principal

Set an estate-wide error catalogue so that services sharing JSON-RPC never collide with the specification's codes or each other's, and so clients can act on codes rather than parse messages.

## The error object When a JSON-RPC 2.0 call fails, the Response carries an `error` member instead of `result`, and that member MUST be an Object with these members: | Member | Rule | |---|---| | `code` | A Number indicating the error type; it MUST be an integer | | `message` | A String with a short description; it SHOULD be one concise sentence | | `data` | Optional; a Primitive or Structured value whose content the Server defines, such as detailed error information or nested errors | The Response still carries `jsonrpc` and `id`, and it MUST NOT carry `result`. ## The reserved codes | Code | Message | Meaning in the specification | |---|---|---| | `-32700` | Parse error | Invalid JSON was received by the server | | `-32600` | Invalid Request | The JSON sent is not a valid Request object | | `-32601` | Method not found | The method does not exist or is not available | | `-32602` | Invalid params | Invalid method parameter(s) | | `-32603` | Internal error | Internal JSON-RPC error | | `-32000` to `-32099` | Server error | Reserved for implementation-defined server errors | Codes from -32768 to -32000 inclusive are reserved for pre-defined errors; any code in that band not listed above is reserved for future use. The remainder of the space is available for **application-defined errors**. ## Choosing the code: follow how far the server got The five named codes line up with the stages a Server passes through, so the first stage that fails picks the code: 1. **Parse the text.** If it is not valid JSON, the answer is `-32700`. The Server has nothing it can read an `id` from. 2. **Check the Request object's shape.** Valid JSON that breaks the Request rules — `jsonrpc` missing or not exactly `"2.0"`, `method` not a String — is `-32600`. 3. **Find the method.** A well-formed Request naming a method that does not exist, or is not available, is `-32601`. 4. **Check the arguments.** The method exists but the parameters do not fit it — wrong count, a missing expected name, a value of the wrong kind — is `-32602`. 5. **Run it.** A failure inside the JSON-RPC machinery itself is `-32603`. Failures that belong to the business — an account that is closed, a quantity over the limit — fit none of those five definitions, and the specification sets aside a different space for them. ## The reserved band and application codes - **-32768 to -32000** is the specification's: the five named codes plus room for future ones. - **-32000 to -32099**, inside that band, is for **implementation-defined server errors** — conditions of the JSON-RPC Server software rather than of the application's domain. Protocols built on JSON-RPC also assign codes of their own there, which is one more reason an application should not. - **Everything else** — positive numbers, small negatives, anything below -32768 — is available for **application-defined errors**. An API documents its own codes there and puts structured detail in `data`. For example, a refused transfer might be answered like this: ```json {"jsonrpc": "2.0", "error": {"code": 4001, "message": "Insufficient funds.", "data": {"balance": 120, "requested": 500}}, "id": "t-55"} ``` ## Why the id is sometimes null The Response's `id` is REQUIRED and MUST equal the Request's `id`. But when there was an error in detecting that `id` — the specification names parse errors and invalid Requests as examples — it MUST be **Null**. The `id` member is never omitted; it is written as `null`. ```json {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null} ``` Two consequences follow: - A Client that receives a null-`id` error cannot pin it to any of its outstanding requests; it only knows that something it sent could not be read. - A Client that itself uses `"id": null` makes its own answers indistinguishable from those failures, which is why the specification says a Request's `id` SHOULD normally not be Null. ## Common mistakes - Answering invalid JSON with `-32600`, or a malformed Request with `-32700`; the first is about the text, the second about the object. - Using `-32601` for arguments that do not match; a method that exists but rejects its input is `-32602`. - Sending a String `code` such as "NOT_FOUND"; the code MUST be an integer. - Packing paragraphs of diagnostics into `message` instead of `data`. - Dropping `id` from an error Response instead of writing `null`.

  • Where should a JSON-RPC 2.0 API put a domain error such as an insufficient-funds refusal?
    Outside the reserved band. Codes -32768 to -32000 belong to the specification, with -32000 to -32099 kept for implementation-defined server errors; the remainder of the space is available for application-defined errors. So use a documented application code, keep message to one concise sentence, and carry structured detail such as the balance in data, whose content the server defines.
  • A JSON-RPC 2.0 server receives {"jsonrpc": "2.0", "method": 7}. Which code applies, and what id goes in the reply?
    -32600 Invalid Request with an id of null. The text is valid JSON, so it is not a parse error, but method MUST be a String, so the object is not a valid Request. It has no id to echo, and the specification says the id MUST be null when it could not be determined, as after an invalid Request.

  • Invalid JSON and a malformed request object both return -32600.
  • Application errors must use codes in the -32000 to -32099 range.
  • An error response may omit id when the server cannot read it.
  • An error code may be a string like NOT_FOUND if it is documented.
  • -32601 means the params did not match the method's signature.