API y empresas

Códigos de estado: qué significa cada uno en la práctica

Un 200 no dice que el vehículo esté sin deuda y un 404 no dice que el dominio no exista. El número califica la solicitud; el resultado de la consulta vive en el cuerpo.

Por Marco Ferreiro ·

Escritorio de madera con tres bandejas metálicas de clasificación apiladas y vacías junto a una carpeta cerrada, con luz natural de ventana.

Una integración consulta un dominio, recibe 200 y el equipo anota que el vehículo está sin deuda. Otra recibe 404 y lo da de baja del padrón. Semanas después aparece un acta anterior a esas consultas y nadie entiende dónde se perdió.

El malentendido no está en el número sino en la pregunta que responde. Un código de estado califica lo que pasó con la solicitud HTTP: si el servidor la entendió, si estaba autorizada, si pudo procesarla. No describe la situación del vehículo. Ese resultado viaja en el cuerpo y puede ser un conjunto vacío, uno incompleto o un aviso de que dos fuentes no contestaron.

RFC 9110 define la semántica de los códigos de uso general y las cinco clases que los agrupan: informativa, satisfactoria, de redirección, de error del cliente y de error del servidor. Exige que el cliente entienda al menos la clase y le permite tratar un código desconocido como el genérico de esa familia, para que no se rompa ante un número que no estaba en su tabla. Esa tolerancia evita una caída; no alcanza para decidir qué informarle al usuario.

Los 2xx no traen la misma noticia

La familia satisfactoria agrupa respuestas distintas:

El 206 es el que más se confunde: pertenece a las solicitudes por rango y no significa “cobertura parcial”. Para decir que una jurisdicción no respondió hace falta un campo explícito. El 304 tampoco es un resultado de negocio: confirma que la representación que el cliente ya tiene sigue sirviendo.

Tratá un 200 con conjunto vacío como interpretable sólo cuando viene acompañado del alcance efectivo de esa consulta, como explicamos en timeout no significa “sin multas”.

Los 4xx acusan a la solicitud

La distinción entre 401 y 403 cambia la conducta del cliente: el primero invita a presentar credenciales; el segundo no mejora repitiendo. El 404 es el más sobreinterpretado: el estándar admite que un servidor lo devuelva cuando prefiere no revelar que el recurso existe. No prueba que el dominio falte en ningún registro ni que no tenga infracciones.

RFC 6585 agrega códigos frecuentes en integraciones: demasiadas solicitudes, precondición requerida y encabezados demasiado grandes. Suma además uno de la familia 5xx para cuando una red intercepta la conexión y exige autenticarse; ese no salió del servicio consultado. Ninguno habla del vehículo.

Los 5xx no hablan del dominio consultado

El 500 indica una condición inesperada del propio servidor; el 502, que un servidor intermediario recibió una respuesta inválida de otro aguas arriba; el 503, indisponibilidad temporal, que puede venir con un intervalo sugerido de espera; el 504, que ese intermediario no obtuvo respuesta a tiempo.

Cuando el backend consulta portales oficiales, cualquiera puede originarse aguas arriba. Convertirlos en “sin infracciones” produce el peor error posible: un vacío que parece un resultado y se guarda como tal. Qué conviene repetir depende de la causa antes que del número, un criterio que desarrollamos en errores que conviene reintentar y errores que no.

El código solo no alcanza para explicar

Tres dígitos no dicen qué campo falló ni qué fuente se cayó. RFC 9457 define un formato de detalle de problema con miembros como tipo, título, estado, detalle e instancia, más extensiones propias del servicio:

{
  "type": "/errores/patente-invalida",
  "title": "Patente inválida",
  "status": 422,
  "detail": "El formato no corresponde a ninguno de los vigentes",
  "instance": "/consultas/qry_7f2"
}

La especificación exige que la respuesta HTTP lleve el mismo código que declara el documento; si difieren, alguien lo cambió en el camino. El detalle, en cambio, no debería incluir datos personales ni credenciales: es texto que termina en logs, tableros y capturas de pantalla.

Qué documentar y qué verificar

El contrato debería enumerar, operación por operación, qué códigos puede devolver el servicio y con qué cuerpo. La especificación OpenAPI prevé eso en su objeto de respuestas, con una entrada por defecto para lo no enumerado. Un código que la integración recibe y el contrato no menciona suele indicar un cambio o un intermediario respondiendo en lugar del servicio.

Antes de conectar, revisá tres cosas: que el cliente decida por familia y no por una lista cerrada de números; que ningún camino de error termine escribiendo “sin infracciones” en la base; y que los estados administrativos de un acta vivan en campos propios en vez de deducirse del código HTTP. Un acta que pasa a pagada no cambia el código de la respuesta que la transporta.

Metodología

Alcance
Semántica de los códigos de estado HTTP en una API de consulta de infracciones y su relación con el resultado de negocio. No cubre el diseño de los estados administrativos de un acta ni las reglas de reintento por causa.
Unidad de análisis
Una respuesta HTTP individual, tomada como código, familia y cuerpo que la acompaña.
Cobertura
Lo dicho sobre cada código proviene de las especificaciones citadas. No se afirma que un portal oficial o un proveedor determinado use ese vocabulario con la misma precisión.

Limitaciones

Fuentes

Preguntas frecuentes

¿Un 200 significa que el vehículo no tiene infracciones?

No. Significa que el servidor pudo procesar la solicitud y entregó una representación del recurso. El conjunto puede venir vacío porque no se encontraron actas o porque una fuente no respondió. Sólo el cuerpo, con el alcance efectivo de la consulta, permite distinguir esos dos casos.

¿Qué diferencia práctica hay entre un 401 y un 403?

El 401 indica que la solicitud no trae credenciales válidas y la respuesta invita a presentarlas. El 403 indica que el servidor entendió el pedido y se niega a atenderlo, sea por credenciales insuficientes o por un motivo ajeno a ellas. Repetir un 403 sin cambiar nada rara vez cambia la respuesta.

¿Un 404 significa que la patente no existe?

No. Significa que el servidor no encontró una representación actual del recurso pedido, y el estándar admite además que un servidor devuelva 404 cuando prefiere no revelar que ese recurso existe. Dice algo sobre la ruta consultada en esa API, no sobre el padrón ni sobre las infracciones del vehículo.

¿Para qué sirve un cuerpo de detalle de problema?

Tres dígitos no dicen qué campo falló ni qué fuente se cayó. RFC 9457 define un formato con miembros como tipo, título, estado, detalle e instancia, más extensiones propias del servicio, para que el cliente reaccione sin analizar texto libre.

Notas relacionadas