API Error Handling Decision Tree

Click status codes for details and recommended actions

API Request Sent
2xx Success ✓
200 OK — Request succeeded, data returned
201 Created — New resource created successfully
204 No Content — Success, no body returned (e.g., DELETE)
Action: Process the response data normally
3xx Redirect ↪
301 Moved — Resource permanently moved
304 Not Modified — Cached version still valid
Action: Follow the Location header automatically
4xx Client Error ⚠️
400 Bad Request — Invalid parameters or body → Fix request data
401 Unauthorized — Missing or invalid credentials → Re-authenticate
403 Forbidden — Valid auth but insufficient permissions → Check roles
404 Not Found — Resource doesn't exist → Verify URL/ID
429 Too Many Requests — Rate limit exceeded → Back off and retry
Action: Fix the request (it's your problem, not the server's)
5xx Server Error 🔥
500 Internal Error — Server bug → Retry, then report
502 Bad Gateway — Upstream service failed → Check status page
503 Unavailable — Server overloaded → Retry with backoff
Action: Retry with exponential backoff; alert monitoring if persistent
Network Error 🌐
Timeout — Server didn't respond in time
DNS failure — Cannot resolve hostname
Connection refused — Server is down
Action: Check connectivity, retry with backoff, show user-friendly error