59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# 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.
|