Course Content
FastAPI Essentials
1 sections · 32 lessons
What are some common error codes returned by FastAPI?
What you need to know
Status codes are grouped by first digit. 4xx means the client should change something; 5xx means the server or something behind it failed. That split tells a client whether retrying makes sense.
Codes FastAPI returns on its own
GET /v1/nope -> 404 {'detail': 'Not Found'}GET /v1/chat (route is POST-only) -> 405 {'detail': 'Method Not Allowed'} Allow: POSTPOST /v1/chat body '{"prompt": "hi"' (broken JSON) -> 422 [{'type': 'json_invalid', 'loc': ['body', 15], 'msg': 'JSON decode error', ...}]POST /v1/chat content-type text/plain -> 422 [{'type': 'model_attributes_type', 'loc': ['body'], ...}]These are real responses. Note that FastAPI uses 422 even for JSON that cannot be parsed, where many other frameworks would say 400. Each item in the 422 detail list has loc (where), msg (what) and type (a stable code clients can match on).
Codes you raise, and what they tell the client
| Code | Meaning | AI-service example | Retry? |
|---|---|---|---|
| 400 | Bad request (semantic) | Prompt contains no text after cleaning | No |
| 401 | Not authenticated | Missing or expired API key or token | After re-auth |
| 403 | Authenticated, not allowed | Free plan calling a pro-only model | No |
| 404 | Not found | Unknown doc_id or run id | No |
| 409 | Conflict | Document already being indexed | Maybe later |
| 413 | Payload too large | 50 MB upload (usually rejected by the proxy) | No |
| 422 | Validation failed | temperature: 5 | No |
| 429 | Too many requests | Rate or token quota hit; send Retry-After | Yes, after the delay |
| 500 | Unhandled error | A bug in your code | Maybe |
| 502 | Bad gateway | Upstream model server returned garbage | Yes, with backoff |
| 503 | Unavailable | Model overloaded or still loading | Yes, with backoff |
| 504 | Gateway timeout | LLM provider took too long | Yes, with backoff |
HTTPException(status_code=429, detail="...", headers={"Retry-After": "30"}) is how you raise any of these; from fastapi import status gives readable names such as status.HTTP_429_TOO_MANY_REQUESTS.
A real-life example
An LLM gateway sits between a company's apps and three model providers. At first it returned 500 for everything that went wrong. Client apps retried every 500 immediately, so when a provider was rate-limiting, the retries tripled the traffic and made the outage worse. When a user sent an invalid temperature, the apps also retried, three times, for an error that could never succeed.
The team mapped errors honestly: provider 429 → gateway 429 with Retry-After; provider timeout → 504; content-policy block → 400 with code: content_blocked; validation → 422. The shared client library retries only 429, 502, 503 and 504, with exponential backoff. Retry traffic during provider incidents dropped sharply, and dashboards could finally separate "users sending bad input" from "we are down".
Follow-up questions to expect
- "Why 422 and not 400 for validation?" — FastAPI's convention: 422 Unprocessable Content means the request was understood but broke the rules. If your organisation standardises on 400, override the
RequestValidationErrorhandler. - "What does the client see on an unhandled exception?" — A plain
500 Internal Server Errorwith no details; the traceback goes only to the server logs. - "Which codes should a client retry?" — 429 (after
Retry-After), 502, 503 and 504, with backoff. Never 4xx validation or auth errors.