Repasa los códigos de estado HTTP que una API debería usar correctamente (no solo 200 y 500)
La mayoría de las APIs usa bien unos seis códigos de estado y tapa todo lo demás con 200 o 500 — este es el vocabulario que un entrevistador espera que domines.
APRENDE HACIENDOPon a prueba tu intuición3 pasos
Repasa los códigos de estado HTTP que una API debería usar correctamente (no solo 200 y 500)
Usa los ejemplos y la explicación de la lección para comprobar tu idea.
Reflexión personal. No se envía a ningún servicio de IA.#Un código de estado es un contrato, no un adorno
Los códigos de estado HTTP son la única parte de una respuesta que cada capa de la cadena —navegadores, SDKs, balanceadores de carga, CDNs, monitoreo, middleware de reintentos— tiene garantizado que va a mirar, incluso cuando no tiene ni idea de qué significa tu cuerpo JSON. Un 200 le dice a todas esas capas "esto funcionó, cacheálo si corresponde, no reintentes". Un 503 les dice "esto es temporal, esperá y reintentá después". Un 401 puede hacer que un cliente refresque un token y repita la petición automáticamente. Cuando una API devuelve 200 OK con { "error": "fondos insuficientes" } en el cuerpo, todas esas capas genéricas reciben la señal equivocada, sin importar qué tan claro le parezca el JSON a una persona que lo lee directamente.
#2xx — éxito, pero cuál tipo
| Código | Significado | Cuándo usarlo de verdad |
|---|---|---|
| 200 OK | Éxito genérico con cuerpo | Lecturas, y escrituras que no encajan en los códigos más específicos de abajo |
| 201 Created | Un recurso nuevo ahora existe | Después de un POST que crea algo — acompañalo con un header Location que apunte al recurso nuevo |
| 202 Accepted | La petición es válida, el trabajo quedó en cola | Procesamiento asíncrono/en segundo plano — todavía no hay un resultado que devolver |
| 204 No Content | Éxito, sin nada que devolver | DELETE, o un PUT/PATCH sin cuerpo significativo que devolver — la respuesta no debe incluir uno |
El error más común acá no es elegir el 2xx equivocado, sino no salir nunca de 200. Una API que devuelve 200 tanto para creación, como borrado, como aceptación asíncrona, está tirando a la basura información que un cliente podría usar automáticamente.
#3xx — redirección, y sí importa cuál
| Código | Significado | Trampa |
|---|---|---|
| 301 Moved Permanently | El recurso vive en una URL nueva, para siempre | Se espera que clientes y crawlers actualicen los enlaces guardados |
| 302 Found | Redirección temporal | Clientes antiguos históricamente reescriben la siguiente petición como GET, perdiendo el método y el cuerpo original |
| 303 See Other | "Repetí esto como un GET, en otro lado" | El código correcto para un flujo post/redirect/get después de un envío de formulario |
| 307 Temporary Redirect | Temporal, pero preserva método y cuerpo | La opción segura al redirigir un POST cuando necesitás que el cuerpo sobreviva |
| 308 Permanent Redirect | Como 301, pero preserva método y cuerpo |
La distinción 302 vs. 307 es una trampa real de entrevista: usar 302 por costumbre en un endpoint POST hace que algunos clientes lo conviertan silenciosamente en un GET sin cuerpo.
#4xx — el cliente hizo algo, y el código debería decir qué
| Código | Significado | Trampa |
|---|---|---|
| 400 Bad Request | La petición está mal formada — ni siquiera se puede parsear | No es para datos válidos pero incorrectos — eso es 422 |
| 401 Unauthorized | En realidad significa no autenticado — sin credenciales o con credenciales inválidas | El nombre en la especificación es famoso por ser engañoso |
| 403 Forbidden | Autenticado, pero sin permiso para hacer esto | El clásico par 401 vs. 403 que preguntan en entrevistas |
| 404 Not Found | El recurso no existe | Algunas APIs devuelven 404 en vez de 403 a propósito, para no confirmar que el recurso existe |
| 405 Method Not Allowed | URL correcta, verbo incorrecto | |
| 409 Conflict | La petición entra en conflicto con el estado actual del servidor | Fallas de concurrencia optimista, creación de recursos duplicados |
| 410 Gone | Existió alguna vez, se eliminó a propósito y para siempre | Se distingue de 404, que solo significa "desconocido" |
| 422 Unprocessable Entity | Petición bien formada, pero semánticamente inválida | Errores de validación de campo sobre un JSON sintácticamente válido |
| 429 Too Many Requests | Se alcanzó el límite de tasa | Debería venir con un header Retry-After |
#5xx — algo se rompió del lado del servidor, pero dónde
| Código | Significado | De dónde suele venir |
|---|---|---|
| 500 Internal Server Error | Comodín genérico | Una excepción sin manejar — el código honesto de "no sabemos" |
| 501 Not Implemented | El servidor no soporta la capacidad pedida | Raro fuera de APIs parcialmente implementadas |
| 502 Bad Gateway | Un proxy inverso/gateway recibió una respuesta inválida de upstream | Generalmente el servicio upstream está roto, no el gateway en sí |
| 503 Service Unavailable | El servidor no puede atender la petición temporalmente | Sobrecarga o mantenimiento planificado — acompañalo con Retry-After |
| 504 Gateway Timeout | El upstream no respondió a tiempo | Distingue "el upstream está lento" de "el upstream mandó basura" (502) |
#La lógica de reintentos debería ramificarse por clase de estado
No todo lo que no es 2xx vale la pena reintentarlo, y tratarlos todos igual es un riesgo real en producción. 429, 503 y 504 están pensados para reintentarse, idealmente con backoff y respetando Retry-After. 400, 401, 403, 404, 409 y 422 no van a tener éxito si reintentás: el problema es la petición en sí, no el momento, así que reintentarlos solo le agrega carga a un sistema que ya te está diciendo que algo está mal. Un cliente HTTP bien construido ramifica su política de reintentos según la clase de estado, en lugar de disparar el mismo loop de backoff ante cualquier cosa que no sea 200.
🧠 Check your understanding
0/4 · 0/4 answered1. Un cliente envía un JSON bien formado, pero el campo "email" no pasa una regla de validación. ¿Qué código de estado encaja mejor?
2. Una petición trae un token de autenticación válido y vigente, pero ese usuario no tiene permiso para borrar este recurso en particular. ¿Qué debería devolver la API?
3. ¿Por qué es riesgoso redirigir un POST con 302?
4. Un cliente limitado por tasa sigue reintentando de inmediato después de recibir 429s y empeora la situación. ¿Qué le falta a la respuesta de la API?