Explorar guías rápidas · APIs

Tecnología: APIsCategoría: Diseño HTTP y de APIsNivel: IntermedioActualizado

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
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Inspeccionar el código de estado con cURL
  5. 2. Inspeccionar encabezados y cuerpo a la vez
  6. 3. Hacer que los scripts fallen ante errores HTTP
  7. 4. 200 OK
  8. 5. 201 Created
  9. 6. 202 Accepted
  10. 7. 204 No Content
  11. 8. 206 Partial Content
  12. 9. 301 Moved Permanently
  13. 10. 302 Found
  14. 11. 303 See Other
  15. 12. 304 Not Modified
  16. 13. 307 Temporary Redirect
  17. 14. 308 Permanent Redirect
  18. 15. 400 Bad Request
  19. 16. 401 Unauthorized
  20. 17. 403 Forbidden
  21. 18. 404 Not Found
  22. 19. 405 Method Not Allowed
  23. 20. 406 Not Acceptable
  24. 21. 408 Request Timeout
  25. 22. 409 Conflict
  26. 23. 410 Gone
  27. 24. 412 Precondition Failed
  28. 25. 413 Content Too Large
  29. 26. 414 URI Too Long
  30. 27. 415 Unsupported Media Type
  31. 28. 422 Unprocessable Content
  32. 29. 428 Precondition Required
  33. 30. 429 Too Many Requests
  34. 31. 431 Request Header Fields Too Large
  35. 32. 500 Internal Server Error
  36. 33. 501 Not Implemented
  37. 34. 502 Bad Gateway
  38. 35. 503 Service Unavailable
  39. 36. 504 Gateway Timeout
  40. 37. Distinguir 408 de 504
  41. 38. Distinguir 400 de 422
  42. 39. Distinguir 409 de 422
  43. 40. Distinguir 401 de 403
  44. 41. Distinguir 404 de las colecciones vacías
  45. 42. No devolver 404 por defecto ante una búsqueda vacía
  46. 43. Usar 201 para la creación, no para cada POST
  47. 44. Usar 204 solo cuando no se necesita cuerpo
  48. 45. Usar 202 para procesamiento asíncrono real
  49. 46. Usar Location para recursos creados o asíncronos cuando sea útil
  50. 47. Usar ETags para la concurrencia optimista
  51. 48. Devolver errores legibles por máquina
  52. 49. No exponer trazas de pila
  53. 50. Incluir un ID de solicitud/correlación
  54. 51. Conservar con criterio los estados upstream útiles
  55. 52. No reenviar a ciegas cada estado upstream
  56. 53. Reintentar solo los estados que encajan con la operación
  57. 54. No reintentar a ciegas la mayoría de los errores 4xx
  58. 55. 409 puede ser reintentable o no
  59. 56. Respetar Retry-After
  60. 57. Aplicar backoff en lugar de reintentar en un bucle cerrado
  61. 58. Usar claves de idempotencia en creaciones reintentables cuando estén admitidas
  62. 59. Comprobar dónde se originó el estado
  63. 60. Comprobar el Content-Type de los errores
  64. 61. Registrar el estado por endpoint e identidad de quien llama de forma segura
  65. 62. Monitorear las clases de estado, no solo 500
  66. 63. Separar los 4xx esperados de los defectos del servidor
  67. 64. Investigar picos repentinos de 401
  68. 65. Investigar picos repentinos de 403
  69. 66. Investigar picos repentinos de 404
  70. 67. Investigar los 429 por identidad y endpoint
  71. 68. Investigar los 500 con IDs de solicitud
  72. 69. Investigar los 502 en la conectividad upstream
  73. 70. Investigar los 503 en la disponibilidad y la sobrecarga
  74. 71. Investigar los 504 en la latencia de las dependencias
  75. 72. No convertir cada excepción en 400
  76. 73. No convertir cada fallo en 500
  77. 74. Mantener estable la semántica de los estados entre versiones
  78. 75. Usar el estado junto con un código de error de dominio
  79. 76. Evitar inventar decenas de códigos numéricos al estilo HTTP
  80. 77. Documentar el comportamiento de los reintentos
  81. 78. Seguir una secuencia de diagnóstico
  82. Qué significa el resultado
  83. Qué revisar
  84. 401 en todos los clientes
  85. 403 solo en una operación
  86. 404 después de un despliegue
  87. 409 durante actualizaciones concurrentes
  88. 422 con un JSON por lo demás válido
  89. 429 seguido de todavía más tráfico
  90. 502 / 504 solo a través del gateway
  91. 500 con HTML en lugar de JSON
  92. Notas de producción
  93. Los códigos de estado forman parte del contrato de la API
  94. No uses solo el código de estado para la observabilidad
  95. Los reintentos son una decisión de sistemas distribuidos
  96. Los gateways pueden reescribir las respuestas
  97. La seguridad puede influir intencionadamente en la elección del estado
  98. Errores comunes
  99. 1. Interpretar 401 como «autenticado pero sin autorización»
  100. 2. Devolver 500 ante errores de validación
  101. 3. Devolver 200 con { "success": false } para cada fallo
  102. 4. Reintentar cada 5xx
  103. 5. Reintentar cada 409
  104. 6. Tratar 202 como un éxito completado
  105. 7. Enviar un cuerpo con 204
  106. 8. Usar 206 para la paginación normal de una API
  107. 9. Suponer que todos los 502/504 provienen del código de la aplicación
  108. 10. Exponer detalles internos de las excepciones en respuestas 500
  109. Siguiente paso
  110. 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-Type
  • Retry-After
  • WWW-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.

Siguiente paso

Usa el estado para orientar la investigación.

  • 400 / 415 / 422 → revisa la sintaxis de la solicitud, el tipo de contenido y la validación.
  • 401 → revisa el token/la clave/el certificado de autenticación, así como el emisor, la audiencia y la caducidad.
  • 403 → revisa el scope, el rol, el tenant y la autorización sobre el recurso.
  • 404 → verifica la ruta, la versión de la API, el ID del recurso y el enrutamiento del gateway.
  • 409 / 412 → revisa la lógica de estado, versión y concurrencia.
  • 429 → revisa la tasa de quien llama, la concurrencia, Retry-After y la política de reintentos.
  • 500 → correlaciona el ID de solicitud con los logs de la aplicación.
  • 502 → revisa la conectividad y la respuesta entre el gateway y el upstream.
  • 503 → revisa la disponibilidad del servicio, la sobrecarga, el mantenimiento y las dependencias.
  • 504 → revisa la latencia upstream y los límites de tiempo de espera.
  • El estado no está claro o es incoherente → reprodúcelo con cURL e inspecciona todos los encabezados y el cuerpo.
  • Necesitas un diagnóstico de extremo a extremo → pasa a Diagnosticar solicitudes de API.

← Todas las guías rápidas