aionboarding/ai-patient-onboarding/docs/ERROR_HANDLING.md

Error Handling & SLA Reference

Module: API Error Contracts & Status Codes

---

1. Standard Error Payload Format

All HTTP error responses (4xx and 5xx) follow FastAPI JSON error contracts:

{
  "detail": "Descriptive human-readable error message explaining why the request failed."
}

Unhandled Internal Server Errors (HTTP 500)

For unhandled exceptions, the global exception handler masks Python tracebacks and returns a sanitized JSON payload:

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected internal server error occurred. Please contact system administration."
  }
}

---

2. Master Error Status Code Guide

HTTP Status Code	Name	Cause	Frontend Action
400 Bad Request	Bad Request	Invalid category, unparseable JSON, or disallowed document format (e.g. .exe).	Validate input parameters before sending request.
401 Unauthorized	Unauthorized	Missing or invalid Authorization: Bearer or X-API-Key header.	Redirect to login or attach valid patient token test_token_<PATIENT_ID>.
403 Forbidden	Forbidden (IDOR)	Authenticated patient_id does not match session owner.	Ensure patient accesses only their own session.
404 Not Found	Not Found	Session ID does not exist in backend database or audio ID expired.	Start a fresh onboarding session via /v1/onboarding/start.
413 Payload Too Large	File Too Large	Uploaded medical document exceeds 10MB (10,485,760 bytes).	Compress or resize file before uploading.
422 Validation Error	Pydantic Error	Request body violates schema rules (e.g. age < 0 or missing required field).	Display field validation message to user.
429 Too Many Requests	Rate Limited	Exceeded rate limit bucket (30 req/min for onboarding; 10 req/min for uploads).	Respect Retry-After: <seconds> response header and back off.
500 Internal Error	Server Error	Unhandled backend logic or database failure.	Show user retry alert and report issue.

---

3. Rate Limit Headers

When HTTP 429 is returned, inspect the response header:

HTTP/1.1 429 Too Many Requests
Retry-After: 59
Content-Type: application/json

{
  "detail": "Rate limit exceeded (30 requests per 60s). Please try again later."
}

Retry-After specifies the exact number of seconds the frontend should pause before retrying.