Explorar guías rápidas · APIs
Códigos de estado HTTP para desarrolladores
Interpreta y usa correctamente los códigos de estado HTTP al construir y diagnosticar APIs, con orientación práctica sobre éxitos, redirecciones, errores del cliente, errores del servidor, reintentos y decisiones de diseño de APIs.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Inspeccionar el código de estado con cURL
- 2. Inspeccionar encabezados y cuerpo a la vez
- 3. Hacer que los scripts fallen ante errores HTTP
- 4. 200 OK
- 5. 201 Created
- 6. 202 Accepted
- 7. 204 No Content
- 8. 206 Partial Content
- 9. 301 Moved Permanently
- 10. 302 Found
- 11. 303 See Other
- 12. 304 Not Modified
- 13. 307 Temporary Redirect
- 14. 308 Permanent Redirect
- 15. 400 Bad Request
- 16. 401 Unauthorized
- 17. 403 Forbidden
- 18. 404 Not Found
- 19. 405 Method Not Allowed
- 20. 406 Not Acceptable
- 21. 408 Request Timeout
- 22. 409 Conflict
- 23. 410 Gone
- 24. 412 Precondition Failed
- 25. 413 Content Too Large
- 26. 414 URI Too Long
- 27. 415 Unsupported Media Type
- 28. 422 Unprocessable Content
- 29. 428 Precondition Required
- 30. 429 Too Many Requests
- 31. 431 Request Header Fields Too Large
- 32. 500 Internal Server Error
- 33. 501 Not Implemented
- 34. 502 Bad Gateway
- 35. 503 Service Unavailable
- 36. 504 Gateway Timeout
- 37. Distinguir 408 de 504
- 38. Distinguir 400 de 422
- 39. Distinguir 409 de 422
- 40. Distinguir 401 de 403
- 41. Distinguir 404 de las colecciones vacías
- 42. No devolver 404 por defecto ante una búsqueda vacía
- 43. Usar 201 para la creación, no para cada POST
- 44. Usar 204 solo cuando no se necesita cuerpo
- 45. Usar 202 para procesamiento asíncrono real
- 46. Usar Location para recursos creados o asíncronos cuando sea útil
- 47. Usar ETags para la concurrencia optimista
- 48. Devolver errores legibles por máquina
- 49. No exponer trazas de pila
- 50. Incluir un ID de solicitud/correlación
- 51. Conservar con criterio los estados upstream útiles
- 52. No reenviar a ciegas cada estado upstream
- 53. Reintentar solo los estados que encajan con la operación
- 54. No reintentar a ciegas la mayoría de los errores 4xx
- 55. 409 puede ser reintentable o no
- 56. Respetar Retry-After
- 57. Aplicar backoff en lugar de reintentar en un bucle cerrado
- 58. Usar claves de idempotencia en creaciones reintentables cuando estén admitidas
- 59. Comprobar dónde se originó el estado
- 60. Comprobar el Content-Type de los errores
- 61. Registrar el estado por endpoint e identidad de quien llama de forma segura
- 62. Monitorear las clases de estado, no solo 500
- 63. Separar los 4xx esperados de los defectos del servidor
- 64. Investigar picos repentinos de 401
- 65. Investigar picos repentinos de 403
- 66. Investigar picos repentinos de 404
- 67. Investigar los 429 por identidad y endpoint
- 68. Investigar los 500 con IDs de solicitud
- 69. Investigar los 502 en la conectividad upstream
- 70. Investigar los 503 en la disponibilidad y la sobrecarga
- 71. Investigar los 504 en la latencia de las dependencias
- 72. No convertir cada excepción en 400
- 73. No convertir cada fallo en 500
- 74. Mantener estable la semántica de los estados entre versiones
- 75. Usar el estado junto con un código de error de dominio
- 76. Evitar inventar decenas de códigos numéricos al estilo HTTP
- 77. Documentar el comportamiento de los reintentos
- 78. Seguir una secuencia de diagnóstico
- Qué significa el resultado
- Qué revisar
- 401 en todos los clientes
- 403 solo en una operación
- 404 después de un despliegue
- 409 durante actualizaciones concurrentes
- 422 con un JSON por lo demás válido
- 429 seguido de todavía más tráfico
- 502 / 504 solo a través del gateway
- 500 con HTML en lugar de JSON
- Notas de producción
- Los códigos de estado forman parte del contrato de la API
- No uses solo el código de estado para la observabilidad
- Los reintentos son una decisión de sistemas distribuidos
- Los gateways pueden reescribir las respuestas
- La seguridad puede influir intencionadamente en la elección del estado
- Errores comunes
- 1. Interpretar 401 como «autenticado pero sin autorización»
- 2. Devolver 500 ante errores de validación
- 3. Devolver 200 con { "success": false } para cada fallo
- 4. Reintentar cada 5xx
- 5. Reintentar cada 409
- 6. Tratar 202 como un éxito completado
- 7. Enviar un cuerpo con 204
- 8. Usar 206 para la paginación normal de una API
- 9. Suponer que todos los 502/504 provienen del código de la aplicación
- 10. Exponer detalles internos de las excepciones en respuestas 500
- Siguiente paso
- Para profundizar
Problema
Una API devolvió 400, 401, 404, 409, 429 o 500, y necesitas saber qué te está diciendo realmente.
Los códigos de estado solo son útiles cuando se interpretan en su contexto.
Un buen proceso de diagnóstico separa:
- problemas de sintaxis de la solicitud
- fallos de autenticación
- fallos de autorización
- recursos inexistentes
- conflictos de estado
- errores de validación
- límites de tasa
- fallos del gateway
- fallos de la aplicación
- problemas temporales de disponibilidad del servicio
El objetivo es usar el código de estado como una señal que orienta la siguiente investigación, no como el diagnóstico completo.
Respuesta rápida
Empieza por la clase del código de estado:
1xx
→ informativo
2xx
→ la solicitud se completó correctamente
3xx
→ redirección / respuesta relacionada con la caché
4xx
→ la solicitud no puede completarse tal como se envió
5xx
→ el servidor o un servicio upstream no pudo completar una solicitud válida
Para los fallos de API más comunes:
400
→ solicitud mal formada o no válida
401
→ autenticación ausente o no válida
403
→ autenticado pero sin permiso
404
→ recurso o ruta no encontrados
409
→ la solicitud entra en conflicto con el estado actual del recurso
412
→ falló la precondición
415
→ tipo de medio de la solicitud no admitido
422
→ solicitud sintácticamente válida pero con fallo semántico/de validación
429
→ límite de tasa / demasiadas solicitudes
500
→ fallo inesperado del servidor
502
→ el upstream devolvió una respuesta no válida/con fallo
503
→ servicio no disponible temporalmente
504
→ se agotó el tiempo de espera del upstream
Inspecciona siempre:
estado
+
encabezados de la respuesta
+
cuerpo de la respuesta
+
ID de solicitud/correlación
antes de decidir dónde está el fallo.
Código / comandos
1. Inspeccionar el código de estado con cURL
curl \
--silent \
--output response.json \
--write-out "%{http_code}\n" \
"https://api.example.com/v1/reports"
Esto guarda el cuerpo por separado e imprime el estado HTTP.
2. Inspeccionar encabezados y cuerpo a la vez
curl \
--include \
"https://api.example.com/v1/reports"
Útil para el diagnóstico interactivo.
Busca:
Content-TypeRetry-AfterWWW-Authenticate- encabezados de caché
- encabezados del gateway/proxy
- IDs de solicitud/correlación
3. Hacer que los scripts fallen ante errores HTTP
curl \
--silent \
--show-error \
--fail-with-body \
"https://api.example.com/v1/reports"
Sin --fail*, cURL puede devolver el código de salida de proceso 0 incluso cuando la respuesta HTTP es 404 o 500.
4. 200 OK
Usos típicos:
GET correcto
actualización síncrona correcta
acción correcta con cuerpo de respuesta
Ejemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"reportId": "rpt-123",
"status": "ready"
}
Úsalo cuando la solicitud se completó correctamente y se devuelve una representación de respuesta normal.
5. 201 Created
Úsalo cuando la solicitud crea correctamente un recurso nuevo.
Respuesta típica:
HTTP/1.1 201 Created
Location: /v1/reports/rpt-123
Content-Type: application/json
{
"reportId": "rpt-123"
}
Cuando sea práctico, devuelve un encabezado Location que identifique el recurso creado.
6. 202 Accepted
Úsalo cuando el servidor acepta la solicitud pero el procesamiento se realizará de forma asíncrona.
Ejemplo:
HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456
{
"jobId": "job-456",
"status": "queued"
}
202 no significa que la operación en segundo plano haya terminado correctamente.
Proporciona un recurso de estado o un mecanismo de callback/eventos cuando quien llama necesite el resultado final.
7. 204 No Content
Úsalo cuando la solicitud se completa correctamente y, de forma intencionada, no hay cuerpo de respuesta.
Usos comunes:
DELETE correcto
actualización correcta sin devolver representación
Ejemplo:
HTTP/1.1 204 No Content
No envíes un cuerpo JSON con una respuesta 204.
8. 206 Partial Content
Se usa para solicitudes de rango (range requests) correctas.
Escenario típico:
descarga de archivos grandes
streaming multimedia
transferencia reanudable
La respuesta incluye encabezados relacionados con rangos, como Content-Range.
No uses 206 solo porque una API devuelva parte de un conjunto de datos lógico mediante paginación.
9. 301 Moved Permanently
Úsalo para una redirección permanente cuando corresponda.
Los clientes pueden almacenar en caché las redirecciones permanentes.
En las APIs, ten cuidado con el comportamiento del método y la compatibilidad de los clientes al redirigir solicitudes que no son GET.
10. 302 Found
Una redirección temporal que históricamente han usado mucho los navegadores y los servidores.
El comportamiento del método en el cliente durante las redirecciones puede variar según el contexto.
En las APIs donde importa conservar el método original, 307 o 308 suele ser más claro.
11. 303 See Other
Útil después de una operación cuando el cliente debe obtener otro recurso con GET.
Ejemplo:
POST crea/inicia la operación
→ 303
→ GET a la URL del resultado/estado
12. 304 Not Modified
Se usa con solicitudes condicionales.
Ejemplo de solicitud:
If-None-Match: "abc123"
Respuesta posible:
HTTP/1.1 304 Not Modified
Esto indica al cliente que su representación en caché todavía puede usarse.
304 no es una respuesta de éxito normal con cuerpo.
13. 307 Temporary Redirect
Redirección temporal que conserva el método HTTP y el cuerpo de la solicitud.
Útil cuando una solicitud de API debe repetirse en otro URI sin convertir un POST/PUT/PATCH en semántica GET.
14. 308 Permanent Redirect
Redirección permanente que conserva la semántica del método y del cuerpo.
Úsala con cuidado, porque las redirecciones permanentes pueden almacenarse en caché.
15. 400 Bad Request
Úsalo cuando la solicitud está mal formada o no puede procesarse debido a la sintaxis o los datos proporcionados por el cliente.
Ejemplos:
JSON no válido
falta un campo obligatorio
sintaxis incorrecta de parámetros de consulta
formato de fecha no válido
Ejemplo de cuerpo:
{
"error": "invalid_request",
"message": "startDate must use YYYY-MM-DD"
}
No devuelvas 500 ante un problema de validación que el cliente puede corregir.
16. 401 Unauthorized
A pesar de su nombre, 401 normalmente significa:
autenticación requerida, ausente o no válida
Ejemplos:
- falta el token Bearer
- token caducado
- firma no válida
- emisor/audiencia del token incorrectos
- credencial de API no válida
En los esquemas de autenticación HTTP, incluye un desafío WWW-Authenticate adecuado cuando corresponda.
17. 403 Forbidden
Úsalo cuando el servidor entiende la solicitud y quien llama está autenticado o identificado de otra forma, pero el acceso no está permitido.
Ejemplos:
- falta un scope requerido
- rol incorrecto
- una política del tenant deniega el acceso
- falla la comprobación de propiedad del recurso
Distinción habitual:
401
→ quién eres / tu credencial no es válida
403
→ sabemos quién eres, pero no puedes hacer esto
18. 404 Not Found
Úsalo cuando no se encuentra el recurso o la ruta solicitados.
Ejemplos:
ID de informe desconocido
ruta incorrecta
recurso eliminado
ruta de versión de API desconocida
Algunas APIs devuelven intencionadamente 404 en lugar de 403 para no revelar si existe un recurso protegido.
19. 405 Method Not Allowed
Úsalo cuando la ruta existe pero no admite el método HTTP solicitado.
Ejemplo:
GET /reports/123
→ admitido
POST /reports/123
→ no admitido
Por lo general, la respuesta debe incluir un encabezado Allow que indique los métodos admitidos.
20. 406 Not Acceptable
Úsalo cuando el servidor no puede producir una representación aceptable según el encabezado Accept del cliente.
Ejemplo:
Accept: application/xml
cuando la API solo admite JSON.
Es menos habitual en APIs que exponen un único formato de respuesta fijo.
21. 408 Request Timeout
Indica que el servidor agotó el tiempo de espera aguardando la solicitud del cliente.
No lo confundas con:
504 Gateway Timeout
que significa que un gateway/proxy agotó el tiempo de espera aguardando a un servicio upstream.
22. 409 Conflict
Úsalo cuando la solicitud entra en conflicto con el estado actual del recurso.
Buenos ejemplos:
clave de negocio única duplicada
conflicto de versión/estado
el recurso ya existe según una regla de unicidad
operación no válida en el estado actual del ciclo de vida
Ejemplo:
{
"error": "state_conflict",
"message": "Report is already finalized."
}
409 suele encajar mejor que un 400 genérico cuando el problema tiene que ver específicamente con el estado actual del recurso.
23. 410 Gone
Úsalo cuando un recurso existió pero se eliminó intencionadamente y el servidor quiere comunicar que su ausencia es permanente.
No lo uses salvo que esa distinción respecto a 404 tenga una utilidad operativa real.
24. 412 Precondition Failed
Se usa cuando falla una precondición de una solicitud condicional.
Ejemplo de solicitud con concurrencia optimista:
If-Match: "version-42"
Si el recurso tiene ahora un ETag distinto:
HTTP/1.1 412 Precondition Failed
Es útil para evitar actualizaciones perdidas.
25. 413 Content Too Large
Úsalo cuando el cuerpo de la solicitud supera los límites que acepta el servidor o un intermediario.
Causas típicas:
- archivo demasiado grande
- payload JSON demasiado grande
- límite de tamaño del cuerpo de la solicitud en el proxy/gateway
El fallo puede producirse antes de que la aplicación reciba la solicitud.
26. 414 URI Too Long
Úsalo cuando el URI de la solicitud supera lo que acepta el servidor o un intermediario.
Causa habitual:
poner un filtro/una lista muy grande en los parámetros de consulta
Traslada las entradas estructuradas de gran tamaño a un cuerpo de solicitud adecuado cuando la semántica de la API lo permita.
27. 415 Unsupported Media Type
Úsalo cuando el Content-Type de la solicitud no es compatible.
Ejemplo:
Content-Type: application/xml
contra un endpoint que solo acepta:
application/json
Comprueba el encabezado real de la solicitud, no solo lo que el código cliente pretendía enviar.
28. 422 Unprocessable Content
Úsalo cuando la sintaxis y el tipo de medio de la solicitud son válidos, pero el contenido no puede procesarse semánticamente.
Ejemplo:
{
"startDate": "2026-11-01",
"endDate": "2026-10-01"
}
Respuesta posible:
HTTP/1.1 422 Unprocessable Content
{
"error": "validation_failed",
"fields": {
"endDate": "Must be on or after startDate"
}
}
Algunas APIs usan 400 para todos los fallos de validación. La coherencia importa más que forzar cada regla de validación a 422.
29. 428 Precondition Required
Úsalo cuando el servidor exige una solicitud condicional para evitar actualizaciones perdidas.
Ejemplo de requisito:
If-Match: "etag-value"
Esto permite imponer la concurrencia optimista.
30. 429 Too Many Requests
Úsalo cuando quien llama ha superado una cuota de tasa o de concurrencia.
Respuesta típica:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Reacción del cliente:
respetar Retry-After
reducir la concurrencia
usar un backoff acotado
evitar tormentas de reintentos
No golpees el servicio todavía más rápido después de recibir un 429.
31. 431 Request Header Fields Too Large
Se usa cuando los encabezados de la solicitud son demasiado grandes.
Causas habituales:
- cookies sobredimensionadas
- JWT muy grandes
- encabezados de proxy repetidos
- exceso de encabezados personalizados
Un gateway puede rechazar la solicitud antes de que llegue a la aplicación.
32. 500 Internal Server Error
Úsalo para fallos inesperados del lado del servidor cuando no se aplica un estado más específico.
Ejemplos:
excepción no controlada
fallo inesperado de un invariante
bug interno
No expongas trazas de pila (stack traces), secretos, SQL ni rutas internas en la respuesta que ve el cliente.
Devuelve un ID de correlación/solicitud para el soporte.
33. 501 Not Implemented
Significa que el servidor no admite la funcionalidad necesaria para atender la solicitud.
Normalmente no es el estado adecuado para:
feature flag desactivado
endpoint no disponible temporalmente
estado no admitido específico de un recurso
Úsalo solo cuando el servidor realmente no implemente la capacidad solicitada.
34. 502 Bad Gateway
Un gateway/proxy recibió una respuesta no válida o fallida de un servidor upstream.
Arquitectura típica:
cliente
→ gateway de API
→ backend
Si el gateway no puede obtener una respuesta válida del backend:
502
Investiga el tramo entre el gateway y el upstream.
35. 503 Service Unavailable
Úsalo cuando el servicio no puede atender solicitudes temporalmente.
Ejemplos:
- mantenimiento
- dependencia sobrecargada
- pool de backends no disponible
- descarte de carga intencionado (load shedding)
Un encabezado Retry-After puede ser útil cuando el servidor sabe cuándo conviene reintentar.
36. 504 Gateway Timeout
Un gateway/proxy no recibió a tiempo una respuesta de un servicio upstream.
Ruta típica:
cliente
→ gateway
→ backend/dependencia lento
No des por hecho que el propio gateway es la causa raíz.
Revisa la latencia upstream y la configuración de los tiempos de espera.
37. Distinguir 408 de 504
408
→ el servidor agotó el tiempo de espera de la solicitud del cliente
504
→ el gateway agotó el tiempo de espera de una respuesta upstream
Esta distinción ayuda a identificar en qué sentido del recorrido de la solicitud se produjo el atasco.
38. Distinguir 400 de 422
Una convención de API útil:
400
→ solicitud mal formada / análisis / validación estructural
422
→ solicitud estructuralmente válida con valores de negocio/semánticos no válidos
Es una convención de diseño, no un requisito para todas las APIs.
Elige un modelo de errores coherente y documéntalo.
39. Distinguir 409 de 422
Usa 409 cuando el fallo se debe principalmente al estado actual del recurso:
conflicto de versión
estado duplicado
transición de ciclo de vida no válida porque el recurso cambió
Usa 422 cuando el propio contenido de la solicitud no supera la validación semántica.
Puede haber solapamiento. La coherencia es lo que importa.
40. Distinguir 401 de 403
No uses:
403 para cualquier error de autenticación
Un patrón más claro es:
autenticación ausente/no válida
→ 401
autenticado pero sin permisos suficientes
→ 403
41. Distinguir 404 de las colecciones vacías
La solicitud:
GET /reports?merchant=abc
sin informes coincidentes puede devolver razonablemente:
200 OK
[]
El endpoint de la colección existe; su resultado está vacío.
En cambio:
GET /reports/nonexistent-id
puede devolver:
404
42. No devolver 404 por defecto ante una búsqueda vacía
Una colección vacía suele ser un resultado válido, no un endpoint o recurso inexistente.
Esta distinción simplifica el comportamiento del cliente.
43. Usar 201 para la creación, no para cada POST
POST no implica automáticamente 201.
Ejemplos:
POST /reports
crea un recurso de informe
→ 201
POST /reports/123/run
inicia una ejecución asíncrona
→ 202
POST /search
devuelve resultados de consulta
→ 200
Elige el estado según el resultado, no solo según el método HTTP.
44. Usar 204 solo cuando no se necesita cuerpo
Si necesitas devolver:
{
"status": "deleted"
}
entonces 200 puede ser más adecuado.
Una respuesta 204 no debe llevar cuerpo de mensaje.
45. Usar 202 para procesamiento asíncrono real
No devuelvas 202 solo para ocultar un trabajo síncrono lento.
Un buen contrato asíncrono debe darle a quien llama una forma de saber cuándo ha terminado:
URL del job
endpoint de estado
webhook
evento
46. Usar Location para recursos creados o asíncronos cuando sea útil
Creación:
HTTP/1.1 201 Created
Location: /v1/reports/rpt-123
Asíncrono:
HTTP/1.1 202 Accepted
Location: /v1/jobs/job-456
Esto hace explícita la siguiente acción del cliente.
47. Usar ETags para la concurrencia optimista
Lectura:
ETag: "42"
Actualización:
If-Match: "42"
Si el recurso cambió:
412 Precondition Failed
Esto evita actualizaciones perdidas de forma silenciosa.
48. Devolver errores legibles por máquina
Prefiere:
{
"error": "validation_failed",
"message": "Request validation failed.",
"fields": {
"startDate": "Required"
},
"requestId": "req-123"
}
en lugar de:
Algo salió mal
Mantén los contratos de error lo bastante estables para que los clientes puedan actuar en función de ellos.
49. No exponer trazas de pila
Mala respuesta en producción:
{
"error": "NullReferenceException at InternalService.cs:842"
}
Devuelve un error externo seguro junto con un ID de solicitud.
Guarda los diagnósticos detallados en logs protegidos del servidor.
50. Incluir un ID de solicitud/correlación
Ejemplo:
{
"error": "internal_error",
"message": "The request could not be completed.",
"requestId": "req-123"
}
El mismo ID debería aparecer en la telemetría del servidor/gateway siempre que sea posible.
51. Conservar con criterio los estados upstream útiles
Si tu API llama a otro servicio, no traduzcas a ciegas cada error upstream en:
500
Ejemplos:
tiempo de espera upstream agotado a través del gateway
→ quizá 504
upstream no disponible
→ quizá 503
el cliente proporcionó un ID de recurso no válido
→ quizá conservar un comportamiento 4xx significativo
Pero no filtres innecesariamente detalles de las dependencias internas.
52. No reenviar a ciegas cada estado upstream
Tu API es responsable de su contrato público.
Un servicio interno puede devolver un estado que no tenga sentido para tu cliente externo.
Traduce de forma deliberada, manteniendo en el servidor la observabilidad del resultado upstream original.
53. Reintentar solo los estados que encajan con la operación
Las condiciones potencialmente reintentables suelen incluir:
429
502
503
504
según la API y la operación.
Pero la seguridad de un reintento también depende de:
método HTTP
idempotencia
efectos secundarios de la solicitud
Retry-After
recomendaciones del proveedor
No uses una lista universal de reintentos.
54. No reintentar a ciegas la mayoría de los errores 4xx
Ejemplos:
400
401
403
404
415
422
suelen requerir que cambie la solicitud, la credencial, el permiso o el recurso.
Un reintento con la misma entrada suele repetir el mismo fallo.
55. 409 puede ser reintentable o no
Ejemplos:
conflicto de concurrencia optimista
→ recargar el recurso y reintentar con la nueva versión
clave duplicada
→ reintentar la misma solicitud de creación no sirve
conflicto temporal de transición de estado
→ quizá reintentar después de que cambie el estado
Interpreta el cuerpo del error y el contrato de negocio.
56. Respetar Retry-After
Retry-After puede devolverse con estados como:
429
503
Los clientes deben usarlo cuando esté presente y sea válido, en lugar de reintentar inmediatamente.
57. Aplicar backoff en lugar de reintentar en un bucle cerrado
Mal:
la solicitud falla
→ reintento inmediato
→ reintento inmediato
→ reintento inmediato
Esto puede empeorar la sobrecarga.
Usa un backoff acotado con jitter cuando corresponda.
58. Usar claves de idempotencia en creaciones reintentables cuando estén admitidas
Ejemplo:
Idempotency-Key: 5f1b...
Si la API lo admite, el servidor puede reconocer los intentos de creación repetidos y evitar efectos secundarios duplicados.
El mecanismo debe implementarlo el servidor; un encabezado aleatorio por sí solo no hace nada.
59. Comprobar dónde se originó el estado
Un 502, 503 o 504 puede proceder de:
- una CDN
- un WAF
- un balanceador de carga
- un API gateway
- un proxy inverso
- la aplicación
Inspecciona los encabezados y el cuerpo.
No des por hecho que la aplicación generó todas las respuestas.
60. Comprobar el Content-Type de los errores
Esperado:
application/json
Recibido:
text/html
Esto suele indicar que un intermediario generó una página de error.
Usa:
curl --include ...
para inspeccionarlo.
61. Registrar el estado por endpoint e identidad de quien llama de forma segura
Dimensiones útiles:
ruta
método
clase de estado
código de estado
identidad del cliente/aplicación
tenant
latencia
ID de solicitud
Evita registrar credenciales o payloads de solicitud sensibles.
62. Monitorear las clases de estado, no solo 500
Vistas operativas útiles:
tasa de 2xx
tasa de 4xx
tasa de 5xx
tasa de 429
latencia por estado
Un aumento repentino de 401, 403, 404 o 429 puede indicar un problema en producción aunque los 500 sigan bajos.
63. Separar los 4xx esperados de los defectos del servidor
Un endpoint con mucha validación puede devolver legítimamente muchas respuestas 400/422.
Desde el punto de vista operativo, distingue:
entradas rechazadas esperadas
de
roturas inesperadas de la integración del cliente
Establece una línea base por endpoint y por cliente.
64. Investigar picos repentinos de 401
Causas posibles:
- clave de firma/certificado caducado
- configuración de despliegue incorrecta
- cambio de audiencia del token
- problema de reloj
- caída del proveedor de autenticación
- fallo en la rotación de credenciales del cliente
Un pico de 401 en muchos clientes es distinto del token caducado de un solo usuario.
65. Investigar picos repentinos de 403
Causas posibles:
- cambio en la política de autorización
- despliegue de scopes/roles
- defecto en el mapeo de tenants
- actualización de la política del gateway
La autenticación puede seguir funcionando correctamente.
66. Investigar picos repentinos de 404
Causas posibles:
- el cliente cambió a una versión de API incorrecta
- cambió el despliegue de rutas
- URL base incorrecta
- IDs de tenant/recurso mal formados
- problema de enrutamiento en el gateway
No todos los 404 significan que se eliminaron datos.
67. Investigar los 429 por identidad y endpoint
Comprueba:
qué clave de API/cliente/usuario
qué endpoint
tasa de solicitudes
concurrencia de solicitudes
comportamiento de reintentos
Un solo cliente agresivo puede generar una carga desproporcionada.
68. Investigar los 500 con IDs de solicitud
El mensaje que ve el cliente debe seguir siendo seguro.
Usa el ID de solicitud para encontrar:
excepción
llamada a dependencia
consulta a la base de datos
paso del pipeline
en la telemetría protegida.
69. Investigar los 502 en la conectividad upstream
Comprueba:
estado del backend
conexión restablecida
respuesta upstream no válida
TLS hacia el backend
logs del proxy/gateway
70. Investigar los 503 en la disponibilidad y la sobrecarga
Comprueba:
número de backends en buen estado
despliegue/mantenimiento
saturación de recursos
deslastre de carga
caída de una dependencia
71. Investigar los 504 en la latencia de las dependencias
Comprueba:
tiempo de espera del gateway
duración en el backend
duración en la base de datos
duración de la API downstream
encolamiento
Aumentar el tiempo de espera puede ocultar el síntoma sin corregir la dependencia lenta.
72. No convertir cada excepción en 400
Un fallo inesperado de la base de datos no es un error de entrada del cliente.
Devuelve un estado del lado del servidor cuando el que falló fue el servidor.
Clasificar mal los errores empeora el monitoreo y el comportamiento de los clientes.
73. No convertir cada fallo en 500
Los errores conocidos del cliente deben usar respuestas 4xx significativas.
Así los clientes pueden corregir su comportamiento sin tratarlo todo como una caída del servicio.
74. Mantener estable la semántica de los estados entre versiones
Si:
creación duplicada
devuelve 409 en un endpoint y 500 en otro, el comportamiento del cliente se vuelve más difícil de implementar.
La coherencia mejora la usabilidad y la operación de la API.
75. Usar el estado junto con un código de error de dominio
Ejemplo:
HTTP/1.1 409 Conflict
{
"error": "report_already_finalized",
"message": "The report cannot be modified after finalization."
}
El estado HTTP aporta el significado general.
El código de error de dominio aporta un significado preciso y legible por máquina.
76. Evitar inventar decenas de códigos numéricos al estilo HTTP
Usa los estados HTTP estándar para la semántica de transporte/API.
Añade un campo de error de dominio estable cuando se necesite más detalle.
77. Documentar el comportamiento de los reintentos
Para cada contrato de error importante, documenta:
estado
error de negocio
¿reintentable?
¿requiere un token nuevo?
¿requiere una nueva versión del recurso?
¿es seguro reintentar automáticamente?
Esto es más útil que publicar solo una lista de códigos de estado.
78. Seguir una secuencia de diagnóstico
1. Capturar el estado HTTP
2. Capturar por separado el error de salida de cURL/del cliente
3. Leer el cuerpo de la respuesta
4. Inspeccionar los encabezados de la respuesta
5. Capturar el ID de solicitud
6. Identificar la capa que respondió
7. Determinar si la responsabilidad es del cliente o del servidor
8. Decidir si es seguro reintentar
9. Correlacionar la telemetría del servidor
Qué significa el resultado
| Código | Interpretación práctica |
|---|---|
200 |
Solicitud completada correctamente |
201 |
Recurso creado |
202 |
Aceptada para procesamiento asíncrono |
204 |
Éxito sin cuerpo de respuesta |
304 |
La representación en caché sigue siendo válida |
400 |
Solicitud incorrecta, mal formada o no válida |
401 |
Autenticación ausente o no válida |
403 |
Quien llama no tiene permiso |
404 |
Ruta/recurso no encontrado |
405 |
Método HTTP no permitido para la ruta |
409 |
Conflicto con el estado actual del recurso |
412 |
Falló la precondición de una solicitud condicional |
413 |
Cuerpo de la solicitud demasiado grande |
415 |
Tipo de medio de la solicitud no admitido |
422 |
Fallo semántico/de validación |
429 |
Límite de tasa superado |
500 |
Fallo inesperado del servidor |
502 |
El gateway recibió una respuesta upstream incorrecta |
503 |
Servicio no disponible temporalmente |
504 |
El gateway agotó el tiempo de espera aguardando al upstream |
El código de estado es una señal de clasificación.
El cuerpo de la respuesta, los encabezados, el contexto de la solicitud y la telemetría del servidor proporcionan el diagnóstico.
Qué revisar
401 en todos los clientes
Sospecha de la infraestructura o la configuración de autenticación compartida antes de suponer que cada credencial caducó por separado.
403 solo en una operación
Revisa el rol, el scope o el permiso sobre el recurso que se requiere.
404 después de un despliegue
Revisa el enrutamiento, la versión y la ruta base antes de suponer que los datos desaparecieron.
409 durante actualizaciones concurrentes
Busca conflictos de concurrencia optimista o de transición de estado.
422 con un JSON por lo demás válido
Revisa las reglas de validación de campos y de negocio.
429 seguido de todavía más tráfico
La política de reintentos del cliente puede estar provocando una tormenta de reintentos (retry storm).
502 / 504 solo a través del gateway
Compara el estado directo del backend y la conectividad/latencia entre el gateway y el backend cuando la arquitectura lo permita.
500 con HTML en lugar de JSON
Es posible que un intermediario haya generado la respuesta.
Inspecciona los encabezados para identificar la capa que respondió.
Notas de producción
Los códigos de estado forman parte del contrato de la API
Cambiarlos puede romper:
- el comportamiento de los reintentos
- el monitoreo
- la lógica de los SDK
- el comportamiento de la interfaz de usuario
- las alertas
Trata la semántica de los estados como un comportamiento versionado.
No uses solo el código de estado para la observabilidad
Registra:
código de error de negocio
ID de solicitud
endpoint
identidad de quien llama
latencia
dependencia upstream
cuando corresponda.
Los reintentos son una decisión de sistemas distribuidos
Un estado puede parecer transitorio, pero reintentar una operación no idempotente puede duplicar efectos secundarios.
Combina la semántica de los estados con garantías de idempotencia.
Los gateways pueden reescribir las respuestas
La aplicación puede devolver un resultado mientras:
- el gateway
- el proxy
- la CDN
- el WAF
cambia el estado o el cuerpo visible desde fuera.
Diagnostica todo el recorrido de la solicitud.
La seguridad puede influir intencionadamente en la elección del estado
Algunas APIs devuelven 404 en lugar de 403 para no revelar la existencia de recursos protegidos.
Documenta y prueba la política elegida.
Errores comunes
1. Interpretar 401 como «autenticado pero sin autorización»
En el uso normal de las APIs HTTP, esa situación suele corresponder a 403.
2. Devolver 500 ante errores de validación
Los clientes no pueden distinguir una entrada incorrecta de un fallo del servicio.
3. Devolver 200 con { "success": false } para cada fallo
Esto oculta la semántica del fallo a los clientes HTTP, los gateways y el monitoreo.
4. Reintentar cada 5xx
El reintento puede ser inseguro o empeorar la sobrecarga.
5. Reintentar cada 409
El significado de un conflicto depende del dominio.
6. Tratar 202 como un éxito completado
Solo significa que la solicitud fue aceptada.
7. Enviar un cuerpo con 204
204 significa que no hay contenido en la respuesta.
8. Usar 206 para la paginación normal de una API
206 corresponde a la semántica HTTP de contenido parcial/rangos, no a conjuntos de datos paginados corrientes.
9. Suponer que todos los 502/504 provienen del código de la aplicación
Con frecuencia los generan los gateways.
10. Exponer detalles internos de las excepciones en respuestas 500
Usa errores seguros junto con un ID de solicitud.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.