Errors and recovery.
Use the error code and request reference to choose the next action.
Updated
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. 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. Exclude tokens, raw personal data and payment details. An error does not by itself establish that a provider consumed nothing.