Error handling
Every error returns a consistent JSON body, regardless of the endpoint.
Shape
error_code— stable code you can use to handle the error programmatically.message— human-readable description of the error.errors— optional; per-field detail on validation errors.
shell
{
"error_code": "VALIDATION_ERROR",
"message": "\"email\" is required",
"errors": {
"email": "required"
}
}Status codes
| Status | Meaning |
|---|---|
| 400 | Invalid request (field validation) |
| 401 | Missing, invalid, or revoked key |
| 403 | The key lacks the required scope |
| 404 | Resource not found (or not in your tenant) |
| 409 | Conflict — resource already exists or state disallows it |
| 422 | Business rule violated (e.g. no availability) |
| 429 | Rate limit exceeded — see Rate limits |
| 500 | Internal error; retry later |
Retry strategy
Retry with exponential backoff on 429, 502, 503 and 504. Don't automatically retry other 4xx: they'll fail the same way.