When things go wrong
Diagnose API errors like an engineer, not by guessing
⏱ Est. ~6 min
01 · Read
APIs break. Servers go down. Keys expire. Rate limits get hit. URLs get typos.
The difference between a beginner and an engineer isn't whether things break — it's how fast you diagnose and fix them.
Systematic approach:
1. Read the status code — what error class is it? 2. Read the response body — the server usually says exactly what's wrong 3. Look at the headers — Retry-After, WWW-Authenticate, X-RateLimit-* are gold 4. Check the URL — one typo breaks everything
Key points
- Always use curl -i for debugging — you need to see the headers
- Error bodies are usually more useful than status codes
- 4xx = your problem. 5xx = their problem.
- If nothing else works, check the API provider's status page
02 · Code example
Diagnosis checklists by status code class.
4xx — Client errors (you did something wrong)
400 Bad Request
→ Check: Is your JSON valid? Are required fields present?
→ Fix: Validate your -d body. Check the API docs for required fields.
401 Unauthorized
→ Check: Did you include the Authorization header? Is the key correct?
→ Fix: Check your API key. Make sure you're using the right header format.
403 Forbidden
→ Check: Do you have permission? Is this feature on your plan?
→ Fix: Check your account permissions or upgrade your plan.
404 Not Found
→ Check: Does the URL path exist? Did you replace all {placeholders}?
→ Fix: Double-check the URL against the docs. Check the resource ID.
429 Too Many Requests
→ Check: Look for Retry-After header — it tells you when to retry.
→ Fix: Slow down. Implement exponential backoff. Use caching.
5xx — Server errors (their problem)
500 Internal Server Error
→ Their code crashed. Check their status page.
→ Retry after a brief wait.
503 Service Unavailable
→ Server is overloaded or in maintenance.
→ Check their status page. Wait and retry.
504 Gateway Timeout
→ Your request took too long. The server gave up.
→ Try again. If persistent, contact the API provider.
curl errors (you didn't even get a response)
curl: (6) Could not resolve host
→ DNS failure. Check the hostname for typos.
→ Verify your internet connection.
curl: (7) Failed to connect
→ Server unreachable or port blocked.
→ Check if the service is down.
curl: (35) SSL certificate problem
→ Certificate expired or invalid.
→ Check if you're using https:// correctly.
03 · Real-machine exercise
Send a request for a GitHub repo that doesn't exist to trigger a real 404.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · Real-machine exercise
Send an unauthenticated request to an endpoint that requires auth to trigger a real 401.
curl -i https://api.github.com/user
05 · Quiz
You call an API and get a 429 status code. What should you do?
- Check your API key
- Change the URL
- Switch to a POST request
- Wait and retry — you've hit the rate limit
06 · Fill in the blank
Status codes starting with 4 mean the error is on the _____ side (your request was wrong).
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.