Errors and troubleshooting
Use the error code and request ID to choose a next step while preserving the original Run.
View as MarkdownRead the error response
HTTP API error responses include requestId and an error object with code, message and retryable. Optional details provide additional context. Keep the request ID when reporting a problem; redact credentials and private input.
MCP tool failures use isError with an error object in structuredContent. An HTTP 200 response from the MCP transport does not prove tool success, and MCP tool errors do not include the HTTP API requestId field.
A retryable error does not mean you should create a new paid task. If submission may have reached the server, reuse the original request and idempotency key.
Response shape · placeholders
{
"requestId": "<request ID>",
"error": {
"code": "<business code>",
"message": "<reason and next step>",
"retryable": false
}
}Choose the next step
| Status | Meaning and next step |
|---|---|
| 401 | Missing, expired or invalid credentials. Configure authorized access, then retrieve the original Run. |
| 403 | The credential lacks permission. Check tool access and Query / Generate permissions. |
| 404 | The resource was not found or is not accessible to this caller. Check its ID and account. |
| 409 | Conflict, including idempotency, revision or funding constraints. Read error.code and error.message before changing anything. |
| 422 | Input validation failed. Inspect the tool and correct the fields that violate its schema. |
| 429 | Rate limit reached. Respect server retry guidance and preserve the original request identity. |
| 503 | A dependency is unavailable. Use bounded retries and recover the original operation if submission was uncertain. |
Fix a local CLI issue
- If purrkey is not found, verify installation and PATH in the environment where your agent actually runs.
- Run purrkey version and purrkey <command> --help to check the installed interface.
- If authentication fails, use purrkey config to enter a key privately. Check ATX_API_URL or a saved API origin if the CLI targets an old deployment.
- If a wait times out, use get-run with the original Run ID instead of making a new request.