API Error Glossary
Rate limiting, exponential backoff, idempotency, circuit breakers, and error classification
API error handling essentials
- Rate limiting (429): too many requests — check Retry-After header, then back off
- Exponential backoff: 1s → 2s → 4s → 8s with random jitter to prevent thundering herd
- Idempotent: safe to retry — same result on multiple calls (GET, PUT, DELETE; POST with Idempotency-Key)
- Circuit breaker: open after failure threshold → fast-fail → half-open test → close on success
- Classify errors before retrying: transient (retry) vs. permanent/business logic (fix first)
Question 0 of 5
A client sends 100 API requests per second but the limit is 60. The API responds with HTTP 429. What is the correct term and what should the client do?
Rate limiting: HTTP 429 Too Many Requests — check Retry-After header, then back off. Key terms:
- Rate limiting: the server enforces a maximum number of requests per time window (e.g., 60 req/sec, 1000 req/hour) — exceeding it returns 429
- Retry-After header: the server tells the client exactly how many seconds to wait before retrying
- Throttling: similar to rate limiting but often refers to slowing responses rather than rejecting — some APIs throttle (slow down) instead of hard-limiting
- Read the
Retry-Afterheader (e.g.,Retry-After: 30= wait 30 seconds) - If no Retry-After, use exponential backoff
- Never retry immediately in a tight loop — this makes the problem worse and can get the client IP banned
Which strategy correctly implements exponential backoff for a failed API request?
Exponential backoff: double the wait time each retry + jitter. Exponential backoff formula:
- Base delay: 1 second
- Retry 1: wait 1s × 2⁰ = 1s
- Retry 2: wait 1s × 2¹ = 2s
- Retry 3: wait 1s × 2² = 4s
- Retry 4: wait 1s × 2³ = 8s
- With jitter: add ±0–1s random delay to each wait to prevent all clients retrying at the same moment
- If 1000 clients all get rate-limited at the same moment and all retry at exactly 30s, they all hammer the server simultaneously
- Random jitter spreads retries across a window, reducing the spike
An API endpoint is idempotent. What does this mean for client retry logic?
Idempotent: safe to retry — multiple calls have the same effect as one. Idempotency by HTTP method:
- GET, HEAD, OPTIONS: always idempotent (read-only, no state change)
- PUT, DELETE: idempotent — PUT the same data again results in the same state; DELETE an already-deleted resource still results in "not found" or 204
- POST: NOT idempotent by default — each call may create a new record
- PATCH: depends on implementation — may or may not be idempotent
- Client sends a unique
Idempotency-Key: uuid-hereheader - Server stores the result for that key
- If the client retries with the same key, the server returns the stored result — no duplicate created
- Stripe, Adyen, and most payment APIs implement this pattern
What is a circuit breaker in the context of API clients, and when does it open?
Circuit breaker: stops calling a failing service — opens after failure threshold, tries again after cooldown. Circuit breaker states:
- Closed (normal): requests flow through; failures are counted
- Open (tripped): after N failures in a window (e.g., 5 failures in 10s), the circuit opens — all requests immediately return an error or fallback without hitting the failing service
- Half-open (testing recovery): after a cooldown period, one request is allowed through; if it succeeds, the circuit closes; if it fails, it opens again
- Without a circuit breaker: a slow or down dependency causes threads/connections to pile up waiting for timeouts — this cascades and takes down the entire system
- With a circuit breaker: the system "fails fast" and returns a degraded but stable response
An API error response includes: "error": "PAYMENT_LIMIT_EXCEEDED", "message": "Daily payment limit of £10,000 reached", "code": 4029, "retry_after": null. What is the correct interpretation?
Business logic error — do not retry; the fix requires user action, not a different request. Classifying API errors for retry decisions:
- Retryable (transient): 429 (rate limit), 503 (service unavailable), 504 (gateway timeout), 500 with no idempotency concern — these may succeed on retry
- Not retryable (permanent): 400 (bad request — fix the payload), 401 (auth — refresh token), 403 (forbidden — check permissions), 404 (not found — resource doesn't exist), 422 (validation — fix the input)
- Business logic errors (this case): domain-specific constraints — "payment limit exceeded", "account suspended", "quota exhausted" — retrying the exact same request will never succeed
error: machine-readable code for programmatic handlingmessage: human-readable explanationcode: internal error code for support team lookupretry_after: null: explicit signal that retrying will not help