API Failure
API failures are a subset of tool failures with their own specific patterns. HTTP status codes carry important information about what went wrong and whether to retry.
API Failure Response Guide
200–299 (Success): no failure — process the response normally
400 Bad Request: your request had bad parameters — do NOT retry without fixing them first
401 Unauthorised: authentication failed — check credentials, escalate if invalid
403 Forbidden: you don't have permission — escalate immediately, do not retry
404 Not Found: resource doesn't exist — skip or use an alternative
409 Conflict: concurrent modification — retry after a short delay with updated data
429 Too Many Requests: rate limited — read Retry-After header, wait, then retry
422 Unprocessable: data format is valid but content is wrong — fix and retry
500 Internal Server Error: server-side bug — retry after a delay
502 Bad Gateway: upstream service failed — retry
503 Service Unavailable: service is down — retry with backoff
504 Gateway Timeout: upstream timeout — retry
Rule: 4xx errors are your fault. Fix the request. 5xx errors are the server's fault. Retry.