Los códigos de estado HTTP son números de tres dígitos que un servidor envía para decirte exactamente qué pasó con tu petición.
El momento en que todo se detuvo
Eran las 11:47 de la noche del viernes. Rodrigo, desarrollador en una startup de logística en Guadalajara, acababa de conectar su app con la API de envíos de una paquetería. Hizo la primera petición de prueba y el servidor respondió. Pero la app simplemente no hacía nada. No mostraba error, no mostraba datos. Solo silencio.
El problema no era el código de Rodrigo. Era que nadie le había explicado cómo leer la respuesta completa. Él miraba el cuerpo del JSON, pero ignoraba algo igual de importante: el número que venía antes.
Ese número era un código de estado HTTP. Y entenderlo habría resuelto su problema en 30 segundos.
El lenguaje secreto del servidor
Cada vez que tu app hace una petición a una API, el servidor responde con dos cosas: un código de estado y un cuerpo de respuesta. La mayoría de los desarrolladores principiantes solo leen el cuerpo. Eso es como leer una carta sin ver el sobre.
El código de estado va en el encabezado de la respuesta HTTP. Es un número entre 100 y 599. Los creadores del protocolo HTTP organizaron estos números en cinco familias. Cada familia tiene una primera cifra que te dice la categoría del resultado.
Los códigos 2xx significan éxito. Los 3xx indican redirecciones. Los 4xx apuntan a un error del cliente. Los 5xx señalan un error del servidor. Conocer estas cinco categorías ya te da ventaja sobre el 40% de los desarrolladores que solo revisan si "llegó algo" en la respuesta.
Los códigos que verás todos los días
No necesitas memorizar los 70 códigos que existen. Con dominar los 8 más comunes, puedes manejar el 95% de los casos reales.
200 OK es el más conocido. Significa que todo salió perfecto. La petición llegó, el servidor la procesó y te devuelve los datos que pediste. Cuando la API de Mercado Libre te regresa la lista de productos de un vendedor, eso es un 200.
201 Created es el 200 del mundo POST. Cuando registras un nuevo cliente en el sistema de FEMSA y el servidor confirma que lo creó, responde con 201. Es sutil pero importante: 200 y 201 no son lo mismo.
204 No Content es interesante porque el éxito no siempre trae datos. Cuando eliminas un recurso con DELETE y la operación funciona, muchas APIs responden 204. Éxito total, cuerpo vacío.
400 Bad Request es la familia 4xx en su forma más básica. Significa que enviaste algo mal formado. Un JSON con errores de sintaxis, un campo requerido vacío, un formato de fecha incorrecto. El servidor entendió tu petición, pero no puede procesar lo que mandaste.
401 Unauthorized no significa que no tienes permiso. Significa que no te identificaste. No enviaste token, enviaste uno expirado o el header de autorización está mal escrito. Es la diferencia entre llegar sin credencial y llegar con una credencial vencida.
403 Forbidden es el paso siguiente. Aquí sí te identificaste, pero no tienes permiso para ese recurso. Si intentas acceder al historial de pedidos de otro usuario en Liverpool con tu propio token válido, recibes 403.
404 Not Found todos lo conocen del navegador, pero en APIs tiene un matiz. No solo significa que la URL no existe. También aparece cuando el recurso específico que buscas no está en la base de datos. Si pides /productos/SKU-99999 y ese SKU no existe, el servidor responde 404.
500 Internal Server Error es la pesadilla. Aquí el problema no es tuyo. El servidor encontró un error interno que no supo manejar. Puede ser un bug en el código del servidor, una base de datos caída o una excepción no controlada. Cuando lo ves, no toques tu código: el problema está del otro lado.
Cómo leer estos códigos en código real
Aquí viene la parte práctica. En Python con la librería requests, leer el código de estado es directo:
import requests
respuesta = requests.get("https://api.tienda.mx/productos/SKU-12345")
if respuesta.status_code == 200:
datos = respuesta.json()
print(f"Producto encontrado: {datos['nombre']}")
elif respuesta.status_code == 404:
print("Este producto no existe en el catálogo.")
elif respuesta.status_code == 401:
print("Tu token expiró. Renuévalo antes de continuar.")
elif respuesta.status_code == 500:
print("Error en el servidor. Intenta más tarde.")
else:
print(f"Respuesta inesperada: {respuesta.status_code}")
Este patrón es el núcleo de cualquier integración robusta. No asumas que la respuesta siempre será exitosa. Siempre valida el código antes de procesar el cuerpo.
Otro enfoque más limpio usa el método raise_for_status():
try:
respuesta = requests.get("https://api.tienda.mx/productos/SKU-12345")
respuesta.raise_for_status()
datos = respuesta.json()
print(f"Precio: ${datos['precio']:,.0f}")
except requests.exceptions.HTTPError as error:
print(f"Error HTTP: {error}")
Este método lanza una excepción automáticamente para cualquier código 4xx o 5xx. Es ideal cuando quieres código más limpio y centralizas el manejo de errores.
El error que Rodrigo no vio venir
Volvamos a Guadalajara. Cuando Rodrigo revisó su código con estos conocimientos, encontró algo revelador. Su petición recibía un 204 No Content. El servidor procesó la acción correctamente, pero no devolvía datos en el cuerpo. Su app esperaba un JSON y, al no encontrarlo, simplemente se congelaba sin avisar nada.
La solución fue agregar una condición: si el código es 204, no intentes leer el cuerpo. Problema resuelto en dos líneas.
Esto ilustra algo que los datos confirman: según estudios de integración de APIs, el 62% de los bugs en consumo de APIs se deben a no manejar correctamente los códigos de estado. No son errores de lógica compleja. Son errores de no leer lo que el servidor ya te está diciendo.
Errores comunes al interpretar códigos
El primero es tratar el 404 como si siempre fuera un error de URL. En APIs REST, un 404 puede ser completamente esperado. Si buscas un producto que no existe, el 404 es la respuesta correcta, no un fallo del sistema.
El segundo es confundir 401 con 403. El 401 dice "no sé quién eres". El 403 dice "sé quién eres, pero no puedes entrar". Actuar igual ante los dos es un error lógico. Para el 401, la solución es renovar o enviar el token. Para el 403, necesitas revisar los permisos del usuario.
El tercero es asumir que un 500 siempre será permanente. Muchos errores 500 son transitorios: un servidor sobrecargado, un timeout de base de datos. La buena práctica es implementar reintentos automáticos con espera exponencial cuando recibes un 500 o un 503.
El cuarto error es ignorar los códigos 3xx. Cuando una API responde 301 o 302, está redirigiendo tu petición a otra URL. La librería requests sigue estas redirecciones automáticamente, pero en otros contextos puedes perder datos si no lo consideras.
Lo que el número te ahorra
Un sistema de pagos para una tienda en línea en México puede recibir miles de peticiones por hora. Sin manejo correcto de códigos de estado, un error 503 durante un pico de tráfico podría reintentar la misma transacción decenas de veces, generando cobros duplicados a los clientes.
Con el manejo correcto, el sistema distingue: 503 es temporal, reintenta en 5 segundos. 400 es un error del cliente, no reintentes. 402 indica problema de pago, notifica al usuario.
Esa distinción no requiere inteligencia artificial ni arquitecturas complejas. Solo requiere leer el número de tres dígitos que el servidor ya te está mandando desde el inicio.
Rodrigo terminó su integración esa misma noche. No cambió su lógica de negocio. Solo aprendió a escuchar lo que el servidor llevaba horas diciéndole.