Rate Limiting and Error Handling
Common API errors
You'll encounter: 429 (rate limited — too many requests), 529 (API overloaded), 400 (malformed request), and 401 (bad API key). Each needs different handling — retries for transient errors, hard failure for auth errors.
Exponential backoff
For 429 and 529 errors, retry with increasing delays (e.g., 1s, 2s, 4s, 8s) rather than immediately hammering the API again. Cap the number of retries (e.g., 3–5) and surface a clear error to the user if all retries fail.
Never expose raw errors to users
Catch and log the actual error server-side, but return a friendly, generic message to the client ("Something went wrong, please try again"). Raw API errors can leak implementation details.
Key Takeaways
- 429 and 529 are transient — retry with exponential backoff.
- 400 and 401 are permanent — fail fast, don't retry.
- Cap retries to avoid infinite loops or runaway costs.
- Never expose raw API error messages directly to end users.
Add retry logic to your API route
Wrap your Claude API call in a retry function with exponential backoff for 429/529 errors, max 3 attempts, and a friendly fallback error response.