Usar correctamente los códigos de estado HTTP: la primera bifurcación del cliente

Qué es

El RFC 9110 define las cinco clases y los códigos individuales; un cliente debe reconocer la clase por el primer dígito y tratar un código desconocido como el código x00 de su clase. En la práctica, algunas distinciones son decisivas: 401 significa que faltan credenciales o que son inválidas, y el servidor debe enviar entonces un encabezado WWW-Authenticate; 403 significa que la autenticación es correcta, pero la acción no está permitida. 404 indica que el destino no existe, o que el servidor no quiere revelar su existencia. 409 informa de un conflicto con el estado actual, 412 de una condición previa fallida como If-Match, 422 de una solicitud sintácticamente correcta pero que no se puede procesar por su contenido. El RFC 6585 añade 428 (condición previa requerida) y 429 (demasiadas solicitudes), este último opcionalmente con Retry-After; 503 es indisponibilidad temporal, también con Retry-After cuando el tiempo de espera es calculable.

Por qué importa

Un cliente ve el código antes de analizar el cuerpo; las bibliotecas, los proxies y las cachés se bifurcan únicamente a partir de él. Muchos clientes reintentan un 503 o un 429, pero no un 400 ni un 422; un 304 ahorra la transferencia, un 201 entrega la dirección del nuevo recurso. Un agente que opera una API a partir de la documentación necesita esta convención para no tener que adivinar ante cada error, y para no repetir, tras un timeout, una solicitud que ya surtió efecto hace tiempo.

Cómo aplicarlo

• Asignar cada clase de error del dominio exactamente a un código y a un tipo de problema legible por máquina; la tabla correspondiente pertenece a la documentación de la API.
• Responder a la creación con 201 y con Location o con el identificador en el cuerpo; responder a la eliminación o revocación exitosas con 204 sin cuerpo.
• Usar 400 para entradas sintácticamente incorrectas y 422 para las inválidas por su contenido, o solo uno de los dos, pero de forma coherente.
• Exigir condiciones previas con If-Match y etiquetas de entidad, y responder con 412 cuando fallan; quien quiera imponerlas responde con 428 a las solicitudes sin condición previa.
• Enviar Retry-After en 429 y 503 siempre que se conozca el tiempo de espera; los clientes y los agentes lo respetan en lugar de reintentar de inmediato.
• Usar 307 o 308 para las redirecciones en las API, que conservan el método y el cuerpo; en 301 y 302, según el RFC 9110, un cliente puede convertir POST en GET por razones históricas.

Trampas

Usar 404 para ocultar decisiones de autorización es legítimo, pero debe aplicarse de forma consistente, porque cualquier desviación delata la existencia del recurso. Los códigos propios fuera de los rangos registrados confunden a los intermediarios. Un 200 con {"error": ...} en el cuerpo se cachea, no se reintenta y el monitoreo lo cuenta como éxito.

Éxito parcial en solicitudes por lotes

Una solicitud que procesa varios elementos tiene varios resultados. El código de estado describe la solicitud como un todo: 200 (o 207 Multi-Status según el RFC 4918) cuando fue aceptada y procesada, y 4xx solo cuando fue inválida en su conjunto. Cada elemento lleva su propio estado y, en su caso, su propio objeto de problema en el cuerpo de la respuesta, en un lugar documentado; GraphQL procede de la misma manera con los errores de campo junto a data. El monitoreo cuenta los errores por elemento por separado de los errores de solicitud, para que un 200 con un noventa por ciento de elementos fallidos no pase por un éxito. Para todo lo demás sigue valiendo la regla del artículo: un error que afecta a toda la solicitud pertenece al código de estado, no a un 200.