Referencia de Códigos de Estado HTTP

Descripción general

Un código de estado es el resumen en una palabra que hace el servidor de lo que ha pasado, y elegir el equivocado tiene consecuencias que van mucho más allá de la pulcritud: cambia si los clientes reintentan, si las cachés guardan la respuesta, si los rastreadores conservan la URL y si un proxy vuelve a procesar la petición.

Esto es una referencia buscable de los códigos que te encuentras de verdad, con la distinción práctica de cada uno en lugar de una reformulación de la especificación.

Cómo se usa

Escribe un número (404) o parte de un nombre (gateway) para filtrar la lista. La coincidencia se busca en los dos campos, así que too many y 429 encuentran la misma entrada.

Las cinco clases

La división entre 4xx y 5xx es la que más importa en la práctica, porque determina el comportamiento de reintento. A un servidor que devuelve 500 para una petición mal formada le llegará esa misma petición mal formada otra vez, y otra, desde todos los clientes bien educados que tengan una política de reintentos. Devolver 400 corta el bucle.

Las distinciones que vale la pena acertar

200 con un error en el cuerpo. Habitual en las API y casi siempre equivocado. Todas las capas que hay entre tú y el cliente —cachés, proxies, monitorización, lógica de reintentos— leen el código de estado, no tu JSON. Un error que devuelve 200 es invisible para todas ellas.

201 frente a 200 al crear. Un 201 debería llevar una cabecera Location que apunte al recurso nuevo. Esa es la parte que usan los clientes; el código por sí solo aporta poco.

202 Accepted. La respuesta correcta para un trabajo que has puesto en cola en lugar de hacer. Es una promesa, así que tiene que decirle al cliente dónde comprobarla: una URL de estado, o un id de trabajo.

204 No Content. Éxito con un cuerpo intencionadamente vacío, típicamente para un DELETE o para un PUT que no devuelve nada. No debe tener ningún cuerpo en absoluto, y no un objeto JSON vacío.

304 Not Modified. La respuesta a una petición condicional cuyo ETag o Last-Modified sigue coincidiendo. No lleva cuerpo, y eso es justamente todo el sentido: el cliente ya tiene los bytes. Si nunca devuelves 304, cada revalidación vuelve a transferir el recurso completo.

400 frente a 422. 400 para una petición que el servidor no pudo analizar: JSON mal formado, un parámetro obligatorio que falta. 422 para una petición que se analizó sin problemas y no pasó la validación. La distinción le dice al cliente si tiene que arreglar su serialización o sus datos.

405 Method Not Allowed. Debe incluir una cabecera Allow con la lista de métodos que sí se aceptan. Sin ella, al cliente le han dicho que no sin darle ninguna salida.

409 Conflict. Para una petición que no se puede aplicar al estado actual: una edición contra una versión obsoleta, un duplicado que viola una restricción de unicidad. No es un «algo ha ido mal» genérico.

410 Gone. Un 404 más fuerte: esto existió y no va a volver. Los rastreadores descartan un 410 más rápido que un 404, que es lo que quieres para contenido que has eliminado a propósito.

429 Too Many Requests. Necesita Retry-After. Sin ella, los clientes adivinan, y adivinan mal: normalmente reintentando de inmediato.

502 frente a 503 frente a 504. 502 significa que un servicio de arriba dio una respuesta no válida. 503 significa que este servidor no está disponible, típicamente sobrecargado o en mantenimiento. 504 significa que un servicio de arriba no respondió a tiempo. Señalan a tres sitios distintos, y usarlos de forma intercambiable hace más difícil localizar una caída.

Ejemplos

• Un rastreador sigue pidiendo una página borrada. Devuelve 410 en lugar de 404.
• Un cliente machaca un endpoint que falla. Comprueba si el fallo devuelve 5xx para lo que en realidad es una condición 4xx.
• El envío de un formulario pierde sus datos detrás de una redirección. La redirección es probablemente un 301 o un 302; cámbiala a 308 o 307.
• Un CDN no cachea una respuesta. Las 2xx y las 3xx son cacheables por defecto; la mayoría de las 4xx no lo son, y las 5xx no deberían serlo nunca.
• Una API devuelve 200 y los clientes ignoran el fallo. No lo están ignorando: nada se lo ha dicho.

Notas

418 I'm a teapot es real, en el sentido de que está registrado y reservado de forma permanente. Viene de una RFC del día de los inocentes y está en la lista porque la gente lo busca.

Los códigos fuera del registro son legales. Un cliente debe tratar cualquier código desconocido según su clase, así que un 299 personalizado se maneja como un éxito y un 599 personalizado como un error de servidor. Usar uno rara vez compensa la confusión que genera.

La lista de aquí cubre los códigos que se usan de verdad. El registro completo lo mantiene la IANA e incluye códigos para WebDAV y otras extensiones que un servicio web típico nunca devuelve.

Para ver qué códigos devuelve realmente una URL en producción, incluida su cadena de redirecciones, usa el verificador de cabeceras HTTP.