Error handling

The Deel MCP server returns errors at two levels: HTTP transport errors and JSON-RPC protocol errors. Understanding both levels helps you diagnose issues and implement appropriate retry strategies.

HTTP errors

HTTP-level errors occur before the JSON-RPC layer processes the request. These indicate transport, authentication, or rate limiting issues.

JSON-RPC errors

JSON-RPC errors are typically returned within an HTTP 200 response, though some errors may be returned with non-200 HTTP statuses (such as 400, 401, or 500) depending on where in the gateway the failure occurs. The error object contains a numeric code and a descriptive message.

Error response format

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "error": {
5
    "code": -32602,
6
    "message": "Invalid params: 'contract_id' is required"
7
  }
8
}

Tool execution errors

Tool execution errors are distinct from JSON-RPC protocol errors. When a tool is invoked successfully at the protocol level but the underlying API operation fails, the server returns a result with isError: true and an error message in the content.

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": {
5
    "content": [
6
      {
7
        "type": "text",
8
        "text": "Error: Contract not found with the specified ID."
9
      }
10
    ],
11
    "isError": true
12
  }
13
}

Common tool execution errors include:

Retry strategies

Not all errors are retryable. Use the following guidance to determine whether to retry a failed request.

Retryable errors

• 429 Too Many Requests: Wait for the duration in the Retry-After header, then retry
• 500 Internal Server Error: Retry with exponential backoff (starting at 1 second, doubling each attempt, maximum 5 retries)
• 502 Bad Gateway and 503 Service Unavailable: Retry with exponential backoff
• -32603 Internal error: Retry with exponential backoff

Non-retryable errors

• 401 Unauthorized: Re-authenticate before retrying
• 403 Forbidden: Request additional scopes; retrying with the same token will not succeed
• -32600 Invalid request and -32602 Invalid params: Fix the request before retrying
• -32601 Method not found: The tool does not exist; verify the tool name
• Tool execution errors (validation, not found): Fix the input parameters before retrying

Rate limits

The Deel MCP server enforces the same rate limits as the Deel REST API. When you exceed the rate limit, the server returns a 429 status code with a Retry-After header indicating the number of seconds to wait.

For detailed rate limit information, see the rate limits documentation.

Next steps