---
since: 0.6.0
---

# API Error Contract

API errors should have a stable machine-readable shape.

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.