# Errors and recovery.

Use the error code and request reference to choose the next action.

Updated: 2026-09-21.
## REST errors

Read the JSON `error.code` and `error.message`, the HTTP status, any retry or recovery fields and the `X-Request-Id` header. The operation-specific contract is in [OpenAPI](/openapi.json). Never parse a human message as a stable identifier.

| Status | Next action |
| --- | --- |
| 400 | Correct the input against the full tool schema. Ask for missing information. |
| 401 | Supply a valid credential or complete the advertised authentication flow. |
| 402 | Read the balance or payment requirement; a human decides whether to add credit. |
| 403 | Review workspace permissions, key restrictions or spending caps. |
| 404 | Check the exact route, tool or authorised run ID. |
| 405 | Use a method listed in the Allow header. |
| 409 | Inspect the existing run or idempotency conflict before retrying. |
| 429 | Respect Retry-After and the reported limit scope; back off. |
| 503 | The service is temporarily unavailable; use a bounded retry. |
| Other 5xx | Preserve the run and idempotency key; the upstream outcome may be uncertain. |

## MCP errors

Protocol errors use JSON-RPC. A tool-level failure is marked `isError`; read its structured result and text for the actual error. A successful protocol response is not proof that an execution succeeded.

## Retrying safely

Do not automatically rerun an operation after a timeout or a network disconnect. Check the existing run or replay the same request with its original idempotency key. Do not change keys, permissions or paid tools to circumvent a rejection.

## Report a problem

Send the request ID, run ID when available, time, endpoint and sanitised error to [support](/contact). Exclude tokens, raw personal data and payment details. An error does not by itself establish that a provider consumed nothing.

---

[HTML page](/docs/errors) · [Agent index](/llms.txt)