> This page is for MCP Server. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.deel.wtf/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server. # Error handling > Handle HTTP and JSON-RPC errors when working with the Deel MCP server 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. | Status code | Meaning | Cause | Resolution | | ----------- | --------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | Unauthorized | Missing, invalid, or expired access token | Re-authenticate using the OAuth2 flow or provide a valid personal access token | | `403` | Forbidden | Token lacks the required scopes for the requested operation at the transport level | Request additional scopes during the OAuth2 authorization flow. Note that scope/permission errors from individual tools are often surfaced as tool execution errors (`isError: true`) rather than HTTP 403 — see [Tool execution errors](#tool-execution-errors) | | `429` | Too Many Requests | Rate limit exceeded | Wait for the duration specified in the `Retry-After` header before retrying | | `500` | Internal Server Error | Unexpected server-side failure | Retry the request after a brief delay. If the error persists, contact Deel support | | `502` | Bad Gateway | Upstream service unavailable | Retry the request after a brief delay | | `503` | Service Unavailable | Server temporarily unable to handle the request | Retry the request with exponential backoff | ## 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 code | Meaning | Cause | Resolution | | ---------- | ---------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `-32700` | Parse error | The request body is not valid JSON | Verify the JSON-RPC request is well-formed | | `-32600` | Invalid request | The JSON-RPC request structure is invalid (missing `jsonrpc`, `method`, or `id` fields) | Ensure the request conforms to the JSON-RPC 2.0 specification | | `-32601` | Method not found | The requested method does not exist on the server | Verify the method name. Use `tools/list` to retrieve available tools | | `-32602` | Invalid params | The parameters provided to the tool are invalid or missing required fields | Check the tool input schema and provide all required parameters with correct types | | `-32603` | Internal error | Server-side error during method execution | Retry the request. If the error persists, contact Deel support | ### Error response format ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: 'contract_id' is required" } } ``` ## 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. ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "Error: Contract not found with the specified ID." } ], "isError": true } } ``` Common tool execution errors include: | Error | Cause | Resolution | | ------------------------ | ------------------------------------------------------- | --------------------------------------------------- | | Insufficient permissions | The access token does not include the required scope | Re-authorize with the necessary scopes | | Resource not found | The specified resource ID does not exist | Verify the resource ID is correct | | Validation error | The input parameters do not meet the API requirements | Check parameter values against the tool description | | Conflict | The operation conflicts with the current resource state | Verify the resource state before retrying | ## 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 > **Tip** > > Implement exponential backoff with jitter when retrying requests. Start with a 1-second delay, double the delay on each retry, and add a random offset to avoid thundering herd issues. Limit retries to a maximum of 5 attempts. ## 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](/api/rate-limits) documentation. ## Next steps #### [Tools reference](/mcp/reference/tools-reference) Browse the full list of available MCP tools #### [Best practices](/mcp/best-practices) Implement production-ready error handling patterns #### [Authorization](/mcp/authorization) Resolve authentication and authorization errors #### [Rate limits](/api/rate-limits) Understand API rate limits and throttling behavior