|
400
|
Bad Request
RFC 9110
|
El servidor no puede procesar la solicitud porque la sintaxis, los parámetros, los encabezados o el cuerpo no son válidos. |
Es común con JSON inválido, valores obligatorios ausentes, URLs mal formadas o encabezados anómalos. |
Revise el formato del cuerpo, Content-Type, los parámetros de consulta y los logs de validación del servidor.
Relacionado: 422
|
|
401
|
Unauthorized
RFC 9110
|
Se requiere autenticación o las credenciales proporcionadas no son válidas. |
Se usa cuando falta un token de login, una clave de API expiró o el encabezado Authorization es incorrecto. |
Revise el encabezado WWW-Authenticate, la expiración del token, el esquema de autenticación y si se envían cookies.
Relacionado: 403, 407
|
|
402
|
Payment Required
RFC 9110
|
Reservado para escenarios que requieren pago, aunque su significado estándar no está ampliamente establecido. |
Algunas API y servicios de pago lo usan de forma no oficial para problemas de pago, crédito o suscripción. |
Revise la documentación específica del servicio para conocer el significado real de 402 y la ruta de recuperación.
Relacionado: 403, 429
|
|
403
|
Forbidden
RFC 9110
|
El servidor entendió la solicitud, pero rechaza permitir el acceso. |
Es común con permisos insuficientes, bloqueos de IP, políticas administrativas o acceso a recursos privados. |
Revise por separado la política de autorización, ACLs, reglas WAF, permisos de archivo y reglas de enrutamiento.
Relacionado: 401, 404, 451
|
|
404
|
Not Found
RFC 9110
|
El recurso solicitado no se encuentra, o el servidor no revela si existe. |
Es más común con errores de URL, páginas eliminadas, rutas incorrectas o recursos ocultos deliberadamente. |
Revise enlaces internos, sitemaps, redirecciones, tablas de rutas y URLs de reemplazo para contenido eliminado.
Relacionado: 410, 403, 451
|
|
405
|
Method Not Allowed
RFC 9110
|
El recurso existe, pero el método HTTP solicitado no está permitido. |
Ocurre cuando se envía POST a una URL solo GET o cuando una ruta de API está configurada para otros métodos. |
Revise el encabezado Allow, las definiciones de método del router y las políticas de restricción de método del proxy.
Relacionado: 404, 501
|
|
406
|
Not Acceptable
RFC 9110
|
El servidor no puede ofrecer una representación que coincida con los encabezados Accept del cliente. |
Puede ocurrir cuando el cliente solicita únicamente tipos de medios, idiomas o codificaciones no admitidos. |
Revise los encabezados Accept, Accept-Language y Accept-Encoding, y la configuración de negociación de contenido del servidor.
Relacionado: 415
|
|
407
|
Proxy Authentication Required
RFC 9110
|
Se requiere autenticación antes de que el cliente pueda usar el proxy. |
Se ve en redes corporativas, proxies de seguridad y entornos de autenticación de gateway. |
Revise los encabezados Proxy-Authenticate y Proxy-Authorization, y la configuración del proxy de red.
Relacionado: 401, 305
|
|
408
|
Request Timeout
RFC 9110
|
El servidor no recibió la solicitud completa del cliente dentro del tiempo que estaba dispuesto a esperar. |
Puede ocurrir con redes lentas, cargas grandes, timeouts de keep-alive o timeouts de balanceadores de carga. |
Revise el comportamiento de reintento del cliente, el tamaño de carga, la configuración keep-alive y los valores de timeout del proxy.
Relacionado: 504
|
|
409
|
Conflict
RFC 9110
|
La solicitud entra en conflicto con el estado actual del recurso. |
Suele usarse para creación duplicada, conflictos de versión, ediciones concurrentes o transiciones de estado inválidas. |
Revise versiones del recurso, ETags, claves duplicadas y reglas de transición de estado del negocio.
Relacionado: 412, 422
|
|
410
|
Gone
RFC 9110
|
El recurso existía antes, pero fue eliminado permanentemente. |
Es más específico que 404 cuando se quiere indicar claramente a buscadores y clientes que una página fue eliminada. |
Use 301 si existe una URL de reemplazo; use 410 con limpieza de sitemap cuando la eliminación permanente sea correcta.
Relacionado: 404, 301
|
|
411
|
Length Required
RFC 9110
|
El servidor rechaza la solicitud porque no incluye Content-Length. |
Puede ocurrir cuando un servidor o gateway necesita conocer de antemano la longitud del cuerpo de la solicitud. |
Revise Content-Length, Transfer-Encoding y el comportamiento de streaming de la biblioteca cliente.
Relacionado: 413
|
|
412
|
Precondition Failed
RFC 9110
|
Falló una precondición de una solicitud condicional, como If-Match. |
Se usa para prevenir ediciones concurrentes, revalidar caché y realizar actualizaciones basadas en ETag. |
Compare If-Match, If-None-Match e If-Unmodified-Since con la versión actual del recurso.
Relacionado: 304, 409, 428
|
|
413
|
Content Too Large
RFC 9110
|
El cuerpo de la solicitud es más grande de lo que el servidor está dispuesto a aceptar. |
Es común con límites de carga de archivos, límites de tamaño de cuerpos JSON y restricciones de tamaño en proxies. |
Revise los límites de carga en servidor, proxy, CDN y aplicación.
Relacionado: 411, 431
|
|
414
|
URI Too Long
RFC 9110
|
La URI de la solicitud es más larga de lo que el servidor puede procesar. |
Puede ocurrir con cadenas de consulta muy largas, bucles de redirección defectuosos o datos excesivos colocados en una URL GET. |
Mueva datos largos al cuerpo de un POST y revise los límites de longitud de URI en proxies y servidores.
Relacionado: 400, 431
|
|
415
|
Unsupported Media Type
RFC 9110
|
El servidor no admite el tipo de medio del cuerpo de la solicitud. |
Ocurre cuando una API JSON recibe un Content-Type incorrecto o se carga un formato de archivo no admitido. |
Revise Content-Type, la extensión del archivo, la configuración multipart y si el parser del servidor está registrado.
Relacionado: 406, 422
|
|
416
|
Range Not Satisfiable
RFC 9110
|
El Range solicitado no puede servirse porque no encaja con el tamaño del recurso. |
Ocurre en descargas reanudables o streaming cuando el rango solicitado queda fuera del tamaño del archivo. |
Revise el encabezado Range, Content-Range, el tamaño del archivo y metadatos de caché obsoletos.
Relacionado: 206
|
|
417
|
Expectation Failed
RFC 9110
|
El servidor no puede cumplir la expectativa indicada en el encabezado Expect. |
Puede ocurrir cuando un servidor o proxy no admite expectativas como Expect: 100-continue. |
Quite el encabezado Expect o confirme que el servidor admita el manejo de 100 Continue.
Relacionado: 100
|
|
418
|
I'm a teapot
RFC 2324 / RFC 9110
|
Un código originado en un RFC de April Fools, con significado principalmente histórico y cultural más que de manejo práctico de errores. |
Algunos servicios lo usan para respuestas lúdicas, pruebas o cultura de desarrolladores, pero no se recomienda para el diseño ordinario de APIs. |
Para APIs de producción, use un código 4xx o 5xx claro con significado bien definido.
Relacionado: 400
|
|
421
|
Misdirected Request
RFC 9110
|
La solicitud se envió a un servidor que no puede producir una respuesta para ella. |
Puede ocurrir cuando la reutilización de conexiones HTTP/2, TLS/SNI, CDN o el enrutamiento de proxy inverso están mal configurados. |
Revise Host, SNI, certificados, coalescencia de conexiones HTTP/2 y enrutamiento de origen del CDN.
Relacionado: 400, 502
|
|
422
|
Unprocessable Content
RFC 9110
|
La sintaxis de la solicitud es válida, pero el contenido no puede procesarse semánticamente. |
Es común en fallos de validación de API, violaciones de reglas de negocio y valores de campo inválidos. |
Defina en las reglas de su API si 400 significa errores de formato y 422 errores semánticos o de validación.
Relacionado: 400, 409, 415
|
|
423
|
Locked
RFC 4918
|
El recurso objetivo está bloqueado, por lo que la solicitud no puede procesarse. |
Se usa para bloqueos de edición de archivos, documentos colaborativos y locks de recursos WebDAV. |
Revise el propietario del lock, su expiración, la API de desbloqueo y la política de manejo de conflictos.
Relacionado: 409, 424
|
|
424
|
Failed Dependency
RFC 4918
|
La solicitud actual no puede realizarse porque falló una operación dependiente previa. |
Se usa cuando varias operaciones dependen entre sí y el fallo de una operación anterior provoca el fallo de una posterior. |
Deje clara en el cuerpo de la respuesta la operación previa fallida y la relación de dependencia.
Relacionado: 207, 423
|
|
425
|
Too Early
RFC 8470
|
El servidor rechaza procesar una solicitud que puede ser demasiado temprana y riesgosa de reproducir. |
Puede usarse con datos tempranos 0-RTT de TLS 1.3 cuando existe riesgo de ataque por replay. |
Asegúrese de que solicitudes no idempotentes no se envíen con 0-RTT y verifique la configuración de cliente y servidor.
Relacionado: 429, 503
|
|
426
|
Upgrade Required
RFC 9110
|
El servidor exige que el cliente actualice protocolos antes de procesar la solicitud. |
Se usa cuando se requiere una actualización concreta, como versión HTTP, TLS o WebSocket. |
Revise el encabezado Upgrade, los protocolos admitidos y si los proxies reenvían solicitudes de actualización.
Relacionado: 101
|
|
428
|
Precondition Required
RFC 6585
|
El servidor exige un encabezado de solicitud condicional. |
Se usa para evitar actualizaciones perdidas en ediciones concurrentes mediante una condición como If-Match. |
Proporcione documentación de API y mensajes de error que indiquen al cliente leer el ETag y actualizar con If-Match.
Relacionado: 412, 409
|
|
429
|
Too Many Requests
RFC 6585
|
El cliente envió demasiadas solicitudes en un periodo determinado. |
Es común con límites de tasa de API, límites de intentos de login, bloqueo de bots y recargas excesivas. |
Revise Retry-After, encabezados de rate limit, límites por usuario o token y estrategia de backoff.
Relacionado: 403, 503
|
|
431
|
Request Header Fields Too Large
RFC 6585
|
Los encabezados de solicitud en conjunto, o un campo de encabezado específico, son demasiado grandes. |
Puede ocurrir cuando las cookies crecen demasiado o se acumulan tokens de autenticación, encabezados de seguimiento o encabezados añadidos por proxies. |
Reduzca el tamaño de Cookie, del encabezado Authorization y de los encabezados añadidos por cadenas de proxies.
Relacionado: 400, 413, 414
|
|
451
|
Unavailable For Legal Reasons
RFC 7725
|
El recurso no puede proporcionarse por razones legales. |
Se usa cuando el acceso a contenido está restringido por órdenes judiciales, solicitudes gubernamentales, avisos de copyright o regulaciones locales. |
Confirme que el código se use para identificar transparentemente una exigencia legal, a diferencia de un 403 o 404 genérico.
Relacionado: 403, 404, 410
|