Quando as coisas dão errado
Diagnostique erros de API como um engenheiro, em vez de adivinhar
⏱ Estim. ~6 min
01 · Ler
APIs quebram, servers caem, keys expiram, rate limits batem, URLs ganham erros de digitação.
A diferença entre iniciante e engenheiro não é se as coisas dão errado — é a velocidade com que você diagnostica e conserta.
Abordagem sistemática:
1. Leia o status code — qual classe de erro? 2. Leia o corpo da resposta — o server geralmente diz exatamente o que está errado 3. Olhe os headers — Retry-After, WWW-Authenticate, X-RateLimit-* são tesouros 4. Cheque a URL — um erro de digitação quebra tudo
Pontos-chave
- Para depurar, sempre use curl -i — você precisa ver os headers
- O corpo do erro costuma ser mais útil que o status code
- 4xx = problema seu. 5xx = problema deles.
- Se nada funcionar, veja a página de status do provedor da API
02 · Exemplo de código
Checklist de diagnóstico por classe de status code.
4xx — Erros do client (você fez algo errado)
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 — Erros do server (problema deles)
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.
Erros do curl (nem chegou a receber resposta)
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 · Prática real
Provoque um 404 real fazendo uma requisição para um repositório do GitHub que não existe.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · Prática real
Provoque um 401 real fazendo uma requisição sem autenticação para um endpoint que exige autenticação.
curl -i https://api.github.com/user
05 · Quiz
Você chama uma API e recebe status code 429. O que fazer?
- Cheque sua API key
- Troque a URL
- Use uma requisição POST
- Espere e tente de novo — você bateu no rate limit
06 · Preencher
Status codes começando com 4 indicam que o erro está do lado do _____ (sua requisição está errada).
Outras lições deste capítulo
⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.
※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.