Error handling and recovery flow
API error response paths and recovery strategies.
Every API team discovers too late that nobody has documented what actually happens when a request fails. This template maps the decision tree from the first validation through authentication, authorization, retryable errors, and unrecoverable server failures — making it clear which path each error type takes and what status code the client receives.
The flow splits at two critical points: first on input validity, then on error classification. This mirrors how most API frameworks dispatch errors, and makes it obvious where you need custom logic.
When to use this template
- API design — before writing handlers, sketch the error paths and decide which conditions are retryable and which require human intervention.
- Documentation — drop this diagram into your API spec so clients see not just the happy path but every error condition and the codes they should expect.
- On-call training — error logs show status codes; this diagram teaches new engineers which ones require immediate action and which are expected transient failures.
How to adapt it
Rename the error type conditions to match your actual validation rules and application errors. Common extensions:
- Add domain-specific validation (email format, balance check, inventory availability) between "Request valid?" and the error classification.
- Insert a circuit breaker decision before the 500 path if you use hystrix or similar patterns.
- Extend the recovery loop to include automatic retries or fallback values for specific error types before returning to the client.
Visual edits regenerate the Mermaid source, so you can move nodes around and still keep your API docs version-control friendly.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[API request received] --> B{Request valid?}
B -->|No| C{Error type?}
B -->|Yes| D[Process request]
D --> E{Success?}
E -->|Yes| F[Return 200 with data]
E -->|No| C
C -->|Validation| G[Return 400 Bad Request]
C -->|Auth| H[Return 401 Unauthorized]
C -->|Permission| I[Return 403 Forbidden]
C -->|Not found| J[Return 404 Not Found]
C -->|Server error| K[Log error]
K --> L{Retryable?}
L -->|Yes| M[Return 429 Too Many Requests]
L -->|No| N[Return 500 Internal Server Error]
G --> O[Client fixes input]
H --> O
I --> O
J --> O
M --> O
N --> P[Alert ops team]
O --> A
Frequently asked questions
- What is an error handling flow diagram?
- It maps every path an API request can take when something goes wrong: from validation failures and auth errors through retryable conditions to unrecoverable server errors. It shows which HTTP status code each branch returns and whether the client should retry, fix input, or escalate to ops.
- What's the difference between a 400, 401, and 403 error?
- 400 (Bad Request) means the client sent malformed input — the request itself is broken. 401 (Unauthorized) means no valid authentication credentials were provided. 403 (Forbidden) means the request is valid but the authenticated user lacks permission. Each points the client toward a different fix.
- When should I return 429 vs 500?
- Return 429 (Too Many Requests) when the error is temporary and the client should back off and retry — rate limiting, transient overload, or resource contention. Return 500 (Internal Server Error) when something on the server is broken and the client's retry won't help — missing dependency, code crash, or data corruption. The client needs to know the difference.
- How do I customize this template for my API?
- Start by renaming the decision nodes to match your real validation steps and error categories. Add business-specific branches — for example, if you have SLA checks or circuit breaker logic, insert them before the generic error classification. Visual edits regenerate clean Mermaid code you can drop into your API documentation.