# 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:

```json
{
  "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:
```json
{
  "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
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.