API error handling flow
Client-side error handling strategies for API requests and failures.
Every API call is a network operation that can fail — the server is down, the user's connection drops, the request takes too long. This template shows the complete decision tree your client should walk through: detect the failure, decide if retrying makes sense, backoff intelligently, and tell the user what happened.
The flow separates transient failures (retry) from permanent ones (show error), and handles the most common trap: hammering a rate-limited or recovering server. Teams use this diagram to agree on resilience before shipping, so users see fast recovery instead of blank screens.
When to use this template
- API client design — before implementing error handling, sketch what retries, when backoff applies, and what users see at each failure point.
- Incident postmortems — after an outage, trace which error path users fell into and which recovery mechanism should have fired.
- Mobile and offline-first apps — where transient failures are common and the retry strategy directly affects user experience.
How to adapt it
Start by listing your actual error codes and behaviors:
- Add a circuit breaker branch after repeated failures (if the service is down for >1 min, stop retrying and route to cache/fallback).
- Insert custom error codes from your API; some may be retryable, others may need user intervention (e.g. payment declined).
- Add a fallback or cached-response path for critical operations so the app can work offline or with stale data.
Visual edits regenerate clean code, so you can adjust retry counts, backoff timing, and error messages in the editor without rewriting Mermaid syntax.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[Send API request] --> B{Response received?}
B -->|No - Timeout| C{Retry count < 3?}
C -->|Yes| D[Wait 1s exponential backoff]
D --> A
C -->|No| E[Log timeout & alert user]
B -->|Yes| F{Status code?}
F -->|4xx - Client Error| G{Is 429 Rate Limit?}
G -->|Yes| H[Wait + retry with backoff]
H --> A
G -->|No| I[Show user error message]
F -->|5xx - Server Error| J{Is retryable?}
J -->|Yes| K[Retry with exponential backoff]
K --> A
J -->|No| L[Log error & notify support]
F -->|2xx - Success| M[Parse response]
M --> N[Update UI state]
Frequently asked questions
- What is an API error handling flow diagram?
- It shows how your client application responds to API failures: timeouts, rate limits, server errors, and invalid inputs. It maps the decision tree — should we retry? Wait and backoff? Show the user a message? — so teams can agree on resilience strategy before code review.
- Why should I retry some errors but not others?
- Retrying is safe for transient failures like timeouts and 5xx errors (the server was temporarily down). Do not retry 4xx errors like 401 (bad auth) or 400 (invalid request) — the request will fail the same way. 429 (rate limit) is safe to retry with exponential backoff so you don't hammer the server while it recovers.
- What is exponential backoff?
- After the first failure, wait 1 second before retry 1. After retry 1 fails, wait 2 seconds. After retry 2 fails, wait 4 seconds. This spreads out your retries so you don't overwhelm a struggling server. Set a maximum (e.g. 32 seconds) to avoid waiting forever.
- How do I adapt this for my API?
- Rename nodes to your real status codes and error types. If your API returns custom error codes, add them as decision branches. For critical operations, you might increase retry count to 5; for user-facing uploads, you might show the user after just 1 retry. Visual edits regenerate clean Mermaid code, so you can sketch your retry strategy without syntax knowledge.
Related templates
Error handling and recovery flow
API error response paths and recovery strategies.
Database reconnect retry pattern
Automatic reconnection with exponential backoff and circuit breaker.
Service degradation strategy
Detect failures, trigger graceful fallbacks, maintain partial service.