Error Handling

API error response format and common status codes

Error Handling

The API uses standard HTTP status codes and returns consistent JSON error objects.

Error Response Format

All errors return a JSON object with an error field:

{
  "error": "Patient not found"
}

Validation errors include a details object mapping field names to arrays of error messages:

{
  "error": "Validation error",
  "details": {
    "name": ["String must contain at least 1 character(s)"]
  }
}

Status Codes

Code	Description
200	Success
201	Resource created
400	Validation error or bad request
401	Missing or invalid API key
403	Insufficient scope for this operation
404	Resource not found
429	Rate limit exceeded
500	Internal server error

A 404 response does not distinguish between “resource does not exist” and “resource belongs to another user” — this is intentional to prevent enumeration attacks.