Cuando las cosas salen mal
Diagnostica errores de API como ingeniero, no a ojo
⏱ Estim. ~6 min
01 · Leer
Las APIs fallan. Los servidores se caen. Las keys vencen. Te chocas con el rate limit. Las URLs tienen typos.
La diferencia entre un principiante y un ingeniero no es que no te pasen cosas — es qué tan rápido las diagnosticas y reparas.
Método sistemático:
1. Lee el status code — ¿qué categoría de error es? 2. Lee el cuerpo de la respuesta — el servidor suele decirte exactamente qué está mal 3. Mira los headers — Retry-After, WWW-Authenticate y X-RateLimit-* son oro 4. Verifica la URL — un typo rompe todo
Puntos clave
- Para depurar, siempre usa curl -i — necesitas ver los headers
- El cuerpo del error suele ser más útil que el status code
- 4xx = tu problema. 5xx = problema de ellos.
- Si nada funciona, revisa la página de estado del proveedor de la API
02 · Ejemplo de código
Lista de diagnóstico por categoría de status code.
4xx — error del cliente (te equivocaste tú)
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 — error del servidor (problema de ellos)
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.
Errores de curl (ni siquiera llegó respuesta)
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áctica real
Provoca un 404 real haciendo una solicitud a un repo de GitHub que no existe.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · Práctica real
Provoca un 401 real haciendo una solicitud sin autenticación a un endpoint que la requiere.
curl -i https://api.github.com/user
05 · Quiz
Llamas a una API y recibes un código 429. ¿Qué hacer?
- Revisar tu API key
- Cambiar la URL
- Cambiar a una solicitud POST
- Esperar y volver a intentar — chocaste con el rate limit
06 · Completar
Los status codes que empiezan con 4 indican que el error está del lado del _____ (tu solicitud).
Otras lecciones de este capítulo
⚠ La experiencia interactiva completa necesita JavaScript. Actívalo y vuelve a cargar la página.
※ Este es un proyecto educativo independiente — no es un producto oficial de Anthropic. Claude™ es una marca registrada de Anthropic, PBC.