How does a JSON-RPC 2.0 server choose among the reserved error codes, and when must the error response's id be null?
answer
- five named codes, one reserved band
- parse, then shape, then method, then arguments
- a range kept for the server software
- application errors live outside the band
- null when the id is unreadable
basics
~20 sJSON-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 sThe `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
Recall the five named codes and what each one means, and that an error response still carries jsonrpc and id but no result.
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.
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.
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.
saying these in an interview costs you the question
- 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.