Errors & troubleshooting
Handle explicit error codes and keep useful context for support.
The error response
Errors use an error object containing code, message, details and trace. Use the machine-readable code for application logic and retain the trace for support. Do not log the bearer credential or sensitive message bodies.
{
"error": {
"code": "idempotency_key_required",
"message": "This operation requires an Idempotency-Key.",
"details": [],
"trace": "<request-trace>"
}
}Common status codes
| Status | What to check |
|---|---|
| 400 | Malformed JSON, unsupported fields or missing request identity |
| 401 | Missing, malformed or invalid credential |
| 403 | Scope, agent binding or workspace access |
| 404 | Resource identity and visibility to this credential |
| 409 | Request identity, draft version or incompatible state |
| 413 | Request body exceeds the 256 KiB limit |
| 422 | Field validation or a rejected configuration |
| 429 | A quota or rate limit; respect the returned retry guidance |
| 503 | A required runtime or capability is unavailable |
Make the next step useful
Keep the endpoint, HTTP status, error code and trace. For state conflicts, read the latest resource before sending a corrected request. Share a redacted reproduction with support, never a real API key.
Need a hand? Get in touch