Error Handling
When authentication or authorization fails, the API returns a JSON error response with one of these codes:
Auth and rate limit errors
| Status | Error | Description |
|---|---|---|
| 401 | missing_api_key | No X-Api-Key header provided |
| 401 | invalid_key_format | Key does not match expected format |
| 401 | invalid_key | Key not found in the system |
| 403 | key_deactivated | Key has been deactivated by an admin |
| 403 | key_revoked | Key has been permanently revoked |
| 403 | key_expired | Key has passed its expiration date |
| 403 | insufficient_scope | Key lacks the required permission scope |
| 429 | rate_limit_exceeded | Too many requests — see Retry-After header |
Operational Errors
| Status | Error | Description |
|---|---|---|
| 400 | invalid_body | Request body is not valid JSON |
| 400 | validation_error | Required field missing or invalid (see detail) |
| 404 | not_found | Resource or endpoint does not exist |
| 405 | method_not_allowed | HTTP method not supported for this endpoint |
| 500 | internal_error | Unexpected server error |
| 500 | query_error | Database query failed |
Error response shape
{
"error": "insufficient_scope",
"detail": "read:products"
}