Error Handling
The API uses standard HTTP status codes and returns structured error responses.
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request — malformed request syntax |
401 | Unauthorized — missing or invalid token |
403 | Forbidden — insufficient permissions |
404 | Not Found — resource does not exist |
409 | Conflict — version mismatch or duplicate |
422 | Validation Error — request body fails validation |
500 | Internal Server Error |
Error Response Format
Validation Errors (422)
When request validation fails, the API returns detailed field-level errors:
json
{
"detail": [
{
"loc": ["body", "first_name"],
"msg": "Field required",
"type": "missing"
}
]
}
Conflict Errors (409)
Returned when optimistic concurrency fails (stale base_version):
json
{
"detail": "Version conflict: expected 3, got 2"
}
Optimistic Concurrency
Many update endpoints use a base_version field for optimistic concurrency control. Always include the current base_version from the entity's last read when updating. If another user modified the entity since your last read, you'll receive a 409 response. Re-fetch the entity and retry with the updated version.
Not Found Errors (404)
json
{
"detail": "Patient not found"
}