API Error Contract
API errors should have a stable machine-readable shape.
On this page ▾
Recommended structure:
json
{
"detail": "Human-readable explanation",
"code": "stable_error_code"
}For validation errors, preserve field-level information when the framework provides it.
Recommended status mapping
| Status | Meaning |
|---|---|
| 400 | Malformed or invalid request |
| 401 | Authentication required/invalid |
| 403 | Authenticated but not authorized |
| 404 | Resource does not exist or is not visible |
| 409 | State/conflict violation |
| 422 | Validation failure where framework semantics use 422 |
| 429 | Rate limit exceeded |
| 500 | Unexpected server error |
Do not expose stack traces, database errors, credentials, or internal service details in production responses.
Something wrong or missing on this page?Report a docs issue