Guía rápida de códigos de estado HTTP

Toda respuesta HTTP empieza con un código de estado de tres dígitos. El primer dígito es la clase; los otros dos la precisan. Esta página reúne los códigos que más verá. Para todos ellos, con búsqueda, use el Búsqueda de Códigos de Estado HTTP.

1xx Informativos

2xx Éxito

3xx Redirección

4xx Error del cliente

5xx Error del servidor

Pares fáciles de confundir

• 401 frente a 403. 401 significa «no sé quién es usted» (inicie sesión, o su token es incorrecto o ha caducado). 403 significa «sé quién es usted y la respuesta es no».
• 301, 302, 307 y 308. El par permanente es 301 y 308; el temporal es 302 y 307. Los más nuevos 307 y 308 garantizan que el método y el cuerpo se repiten sin cambios, mientras que clientes antiguos pueden convertir un POST con 301 o 302 en un GET.
• 404 frente a 410. Ambos significan «aquí no está». 410 indica que se eliminó a propósito y no volverá, lo que ayuda a los buscadores a olvidar la URL antes.
• 502, 503 y 504. 502: el servidor de origen respondió mal. 503: el servicio está caído o sobrecargado, a propósito o sin querer. 504: el servidor de origen no respondió a tiempo.
• 400 frente a 422. 400 es para peticiones que el servidor no puede interpretar; 422 para las que interpretó bien pero no puede aceptar, como un JSON válido con un correo inválido.

Elegir un código para una API

• Devuelva 200 con cuerpo en lecturas y actualizaciones, 201 con cabecera Location en creaciones y 204 cuando no hay nada que devolver.
• Use 404 para un recurso inexistente y 409 para un conflicto, no 400 para todo.
• Use 401 solo con un desafío de autenticación y 403 para problemas de permisos.
• Añada Retry-After a 429 y 503 para que los clientes sepan cuándo reintentar.
• No esconda errores tras un 200: las herramientas de monitorización, las cachés y los clientes dependen del código de estado.

Lectura relacionada: HTTP, Redirección, Limitación de tasa (rate limiting) y Guía rápida de cabeceras HTTP.