JSON-RPC Error Codes Reference

Overview

In JSON-RPC, error handling is standardized through a system of error codes that provide information about what went wrong during a request. The error object structure in JSON-RPC 2.0 includes a numeric code, a short message, and an optional data field for additional details.

This reference documents both the standard error codes defined in the JSON-RPC 2.0 specification and recommended practices for creating custom error codes in your own implementations.

Error Object Structure

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32700,           // Error code (number)
    "message": "Parse error",  // Short message (string)
    "data": {                  // Optional additional information
      "details": "Invalid JSON at line 1",
      "line": 1,
      "column": 34
    }
  },
  "id": null                   // Request ID or null
}

Standard Error Codes

The JSON-RPC 2.0 specification defines the following standard error codes:

Code	Message	Meaning
-32700	Parse error	Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600	Invalid Request	The JSON sent is not a valid Request object.
-32601	Method not found	The method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.

Note: All standard error codes are negative numbers in the range -32768 to -32000. The codes -32099 to -32000 are reserved for implementation-defined server errors.

Reserved Server Error Codes

The range from -32099 to -32000 is reserved for implementation-defined server errors. Here are some common server error codes within this range:

Code	Message	Meaning
-32000	Server error	Generic server error, used when no more specific error is applicable.
-32001	Server overloaded	Server is currently unable to handle the request due to a temporary overload.
-32002	Rate limit exceeded	Too many requests have been sent within a given time period.
-32003	Session expired	The session or authentication has expired.
-32004	Method not ready	The method exists but is temporarily unavailable.

Implementation-Specific Errors

In addition to the standard errors, many JSON-RPC implementations use specific error codes for common scenarios. While these are not part of the official specification, they are widely recognized:

Code	Message	Meaning
-32040	Invalid batch request	The batch request contains an invalid or empty array.
-32050	Content-Type error	The Content-Type header is missing or not set to application/json.
-32060	Transport error	Error occurred during transport or connection.
-32070	Timeout error	The request timed out before a response was received.

Custom Error Codes

For application-specific errors, the JSON-RPC 2.0 specification allows using any error code outside the reserved range (-32768 to -32000). Custom error codes are typically chosen based on the specific needs of your application.

Recommended Ranges

Range	Usage
-32768 to -32000	Reserved - Do not use (reserved for pre-defined errors)
-31999 to -1	Recommended for general application errors
1 to 999	Recommended for validation and input errors
1000 to 4999	Recommended for business logic errors
5000+	Recommended for system or infrastructure errors

Example Custom Error Codes

Code	Message	Meaning
100	Invalid format	A parameter was provided in an invalid format.
101	Missing field	A required field is missing from the request.
1001	Unauthorized	The user is not authorized to perform this action.
1002	Resource not found	The requested resource could not be found.
5001	Database error	An error occurred while accessing the database.

Error Design Guidelines

When designing an error handling system for your JSON-RPC API, consider the following best practices:

Be Specific and Descriptive

Use specific error codes that clearly identify the problem. Include helpful error messages that explain what went wrong.

Use the Data Field Effectively

Include additional context in the data field to help clients understand and resolve the error.

"error": {
  "code": 101,
  "message": "Missing field",
  "data": {
    "field": "email",
    "location": "params.user",
    "description": "Email address is required"
  }
}

Document Your Error Codes

Maintain thorough documentation of all custom error codes, including their meaning and possible solutions.

Group Related Errors

Organize error codes into ranges or categories to make them more predictable and easier to handle.

Be Consistent

Use the same error code for the same error condition throughout your API. Avoid changing error codes over time.

Client-Side Error Handling

Properly handling JSON-RPC errors on the client side is critical for creating robust applications. Here's an example of how to handle errors in JavaScript:

async function callJsonRpcMethod(method, params) {
  try {
    const response = await fetch('https://api.example.com/jsonrpc', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: method,
        params: params,
        id: generateId()
      })
    });
    
    const data = await response.json();
    
    // Check for JSON-RPC error
    if (data.error) {
      switch (data.error.code) {
        // Handle standard errors
        case -32700:
          console.error('Parse error: Invalid JSON');
          break;
        case -32600:
          console.error('Invalid request');
          break;
        case -32601:
          console.error('Method not found:', method);
          break;
        case -32602:
          console.error('Invalid parameters:', params);
          break;
          
        // Handle custom application errors
        case 1001:
          console.error('Authentication required');
          // Redirect to login page
          break;
        case 1002:
          console.error('Resource not found:', data.error.data?.resource);
          break;
          
        default:
          // Generic error handler
          console.error('JSON-RPC error:', data.error.message);
      }
      
      throw new JsonRpcError(data.error.code, data.error.message, data.error.data);
    }
    
    // Return result if no error
    return data.result;
  } catch (error) {
    // Handle network or other errors
    if (!(error instanceof JsonRpcError)) {
      console.error('Network or client error:', error);
    }
    throw error;
  }
}

Error Handling Best Practices

Always check for the presence of an error property in the response
Handle both standard and custom error codes appropriately
Include error handling for network and transport issues
Log errors with sufficient context for debugging
Consider different handling for different error categories (validation errors vs. server errors)
Provide user-friendly error messages in the UI

Tip: Create a dedicated JsonRpcError class to standardize error handling throughout your application.