Cuando se realizan solicitudes a la API a través de Apigee, los componentes de Apigee Routers y Message Processors, o los servidores backend, pueden devolver errores a las aplicaciones cliente.
Errores del procesador de mensajes
El procesador de mensajes es el componente principal de Apigee que procesa las políticas e interactúa con los servidores backend. Puede devolver errores si detecta algún problema, como los siguientes:
Problemas de conectividad de red, errores de handshake TLS, falta de disponibilidad del servidor backend,
falta de respuesta durante la comunicación con el servidor backend
Errores durante la ejecución de la política
Encabezados HTTP, codificación o ruta no válidos, incumplimiento de las especificaciones HTTP, superación de los límites de producto, etc.:
Con la solicitud HTTP enviada por las aplicaciones cliente
O
Con la respuesta HTTP enviada por el servidor backend
Muchos otros más
Error de ejemplo del procesador de mensajes
El procesador de mensajes siempre devuelve un código de estado HTTP seguido de un mensaje de error junto con un código de error en formato JSON, como se muestra a continuación:
La aplicación cliente recibe un código de respuesta como el siguiente ejemplo:
HTTP/1.1 504 Gateway Timeout
Una respuesta de error del procesador de mensajes tiene el siguiente formato:
Descripción de los campos de la respuesta de error:
Campo
Descripción
faultstring
Contiene el mensaje de error que describe la posible causa del error.
errorcode
Código de error (también denominado código de fallo) asociado al error.
reason
Contiene un mensaje que indica el posible motivo del error.
Catálogo de errores de tiempo de ejecución
Este catálogo de errores proporciona toda la información que necesitas saber sobre los códigos de error de tiempo de ejecución (para errores que no infringen las políticas) que devuelve el componente Message Processor de Apigee. Incluye la siguiente información sobre cada uno de los códigos de error:
Código de estado HTTP
Mensaje de error
Motivo del error (no todos los mensajes de error muestran un
reason)
Posibles causas del error
Cualquier especificación HTTP asociada o límite de producto
Manuales y vídeos con instrucciones para diagnosticar la causa del error y soluciones eficaces que puedes aplicar para resolver el error por tu cuenta (si están disponibles)
Solución que puedes aplicar para resolver el error por tu cuenta
Se incluyen las siguientes categorías de códigos de error:
Use el cuadro Buscar de abajo para filtrar la tabla y mostrar la información anterior
de un código de error específico. Puedes buscar el código de estado o cualquier contenido en cualquier campo de la tabla.
searchBúsqueda
Código de error
Descripción
Solucionar
flow.*
flow.APITimedOut
Código de estado HTTP:
504 Gateway Timeout
Mensaje de error:
API timed out
Causa posible:
Este error se produce si:
El servidor backend no responde en el periodo de tiempo de espera configurado
por la propiedad
api.timeout del proxy de API específico.
Una política tarda mucho tiempo debido a operaciones que requieren muchos recursos computacionales, una carga elevada o un rendimiento deficiente.
flow.SharedFlowNotFound
Código de estado HTTP:
500 Internal Server Error
Mensaje de error:
Shared Flow {shared_flow_name} Not Found
Causa posible:
Este error se produce si el flujo compartido específico:
La codificación especificada en el encabezado de solicitud HTTP
Content-Encoding es válida y compatible con Apigee.
PERO
El formato de la carga útil que envía el cliente como parte de la solicitud HTTP no coincide con el formato de codificación especificado en el encabezado Content-Encoding.
La codificación especificada en el encabezado de respuesta HTTP Content-Encoding del servidor de backend o de destino es válida y compatible con Apigee.
PERO
El formato de la carga útil enviada por el servidor backend o de destino como parte de la respuesta HTTP no coincide con el formato de codificación especificado en el encabezado Content-Encoding.
messaging.adaptors.http.flow.ErrorResponseCode
Código de estado HTTP:
500
Mensaje de error:
El mensaje de error y el formato pueden variar en función de la implementación del servidor backend.
Causa posible:
Este error se produce si el servidor backend responde a Apigee con el código de estado 500.
Código de estado HTTP:
503
Mensaje de error:
El mensaje de error y el formato pueden variar en función de la implementación del servidor backend.
Causa posible:
Este error se produce si el servidor backend responde a Apigee con el código de estado 503.
Código de estado HTTP:
504
Mensaje de error:
El mensaje de error y el formato pueden variar en función de la implementación del servidor backend.
Causa posible:
Este error se produce si el servidor backend responde a Apigee con el código de estado 504.
Nota: El código de error
messaging.adaptors.http.flow.ErrorResponseCode no se devuelve
como parte del mensaje de error enviado a las aplicaciones cliente. Esto se debe a que Apigee define este código de error siempre que el servidor backend responde con un error y con cualquiera de los códigos de estado 4XX o 5XX. Puede ver este código de error en Monitorización de APIs o en la base de datos de analíticas.
messaging.adaptors.http.flow.GatewayTimeout
Código de estado HTTP:
504 Gateway Timeout
Mensaje de error:
Gateway Timeout
Motivo:
TARGET_READ_TIMEOUT
Causa posible:
Este error se produce si el servidor backend no responde al Message Processor de Apigee en el periodo de tiempo de espera de E/S configurado en el Message Processor.
messaging.adaptors.http.flow.InternalServerError
Código de estado HTTP:
500 Internal Server Error
Mensaje de error:
Internal server error at backend
Motivo:
SERVER_ERROR
Causa posible:
Este error se produce en uno de los siguientes casos:
La aplicación backend ha detectado una excepción o un error no controlados al procesar la solicitud de Apigee. Esto puede deberse a problemas como una lógica defectuosa, entradas inesperadas u otros problemas de tiempo de ejecución en el código de la aplicación.
Es posible que el servidor backend no se haya podido conectar a su base de datos o que se haya producido un error en una consulta de la base de datos. Esto puede deberse a la conectividad de red, a que las credenciales de la base de datos sean incorrectas, a que el servidor de la base de datos esté inactivo o a problemas con el esquema o los datos de la base de datos.
Si tu servidor backend depende de otros servicios internos o externos, como APIs, colas de mensajes o sistemas de almacenamiento en caché, un fallo en una de estas dependencias puede provocar que devuelva un error 500 a Apigee. Es posible que el backend no pueda comunicarse con el servicio dependiente o que reciba respuestas de error de él.
El servidor backend puede estar sobrecargado debido a un tráfico elevado, a que no tiene suficiente memoria (RAM), a que utiliza demasiada CPU o a que tiene poco espacio en disco. Cuando el servidor no tiene suficientes recursos, no puede procesar las solicitudes y responde con un error 500.
Si la configuración del servidor backend es incorrecta, pueden producirse errores inesperados durante el procesamiento de las solicitudes. Esto incluye problemas con las configuraciones del servidor, los ajustes de la aplicación o las configuraciones de implementación.
Puede haber un error subyacente en el código de la aplicación de backend que se active por la solicitud específica de Apigee. Es posible que estos errores no sean evidentes en circunstancias normales, pero se manifiestan con determinados patrones de solicitudes o datos.
messaging.adaptors.http.flow.LengthRequired
Código de estado HTTP:
411 Length Required
Mensaje de error:
'Content-Length' is missing
Motivo:
CLIENT_REQUEST_CONTENT_LENGTH_REQUIRED
Causa posible:
Este error se produce si la aplicación cliente no transfiere el encabezado Content-Length como parte de las solicitudes HTTP POST y PUT enviadas a Apigee.
Nota: Las solicitudes que fallan con este error no se pueden registrar en la herramienta de seguimiento, ya que el procesador de mensajes realiza esta validación en una fase muy temprana, mucho antes de procesar la solicitud y de ejecutar cualquier política en el proxy de API.
Asegúrate de que la aplicación cliente siempre transmita el encabezado Content-Length como parte de las solicitudes HTTP POST y PUT enviadas a Apigee. Por ejemplo:
curl -X POST https://HOSTALIAS/PATH -d '{"name": "abc"}' -H "Content-Length: 15"
Aunque envíes una carga útil vacía con solicitudes POST y PUT, asegúrate de que se envíe el encabezado Content-Length: 0. Por ejemplo:
curl -X POST https://HOSTALIAS/PATH -H "Content-Length: 0"
messaging.adaptors.http.flow.NoActiveTargets
Código de estado HTTP:
503 Service Unavailable
Mensaje de error:
The Service is temporarily unavailable
Motivo:
TARGET_HEALTHCHECK_CONNECT_TIMEOUT
TARGET_HEALTHCHECK_CONNECTION_REFUSED
TARGET_HEALTHCHECK_HTTPS_REQUEST_OVER_HTTP
TARGET_HEALTHCHECK_UNEXPECTED_EOF
Causa posible:
Este error se produce en uno de los siguientes casos si usas
TargetServer en Apigee:
La resolución de DNS incorrecta del host del servidor backend
por parte del servidor de autorización personalizado ha provocado que las direcciones IP sean incorrectas, lo que ha derivado en
errores de conexión.
Errores de tiempo de espera de conexión debido a lo siguiente:
La restricción del cortafuegos en el servidor backend impide que Apigee se conecte al servidor backend.
Problemas de conectividad de red entre Apigee y el servidor backend.
El host especificado en TargetServer es incorrecto o
tiene caracteres no deseados (como un espacio).
Este error también puede producirse si fallan las comprobaciones del estado configuradas para monitorizar el estado de los servidores de destino.
messaging.adaptors.http.flow.RequestTimeOut
Código de estado HTTP:
408 Request Timeout
Mensaje de error:
Request timed out
Motivo:
CLIENT_READ_TIMEOUT
Causa posible:
Este error se produce si el procesador de mensajes de Apigee no recibe la carga útil de la solicitud de la aplicación cliente durante el periodo de tiempo de espera de E/S configurado en el componente Message Processor.
Solucionar
Asegúrate de que la aplicación cliente envíe la carga útil de la solicitud dentro del periodo de tiempo de espera de E/S configurado en el componente Message Processor de Apigee.
messaging.adaptors.http.flow.ServiceUnavailable
Código de estado HTTP:
503 Service Unavailable
Mensaje de error:
The Service is temporarily unavailable
Motivo:
TARGET_CONNECT_TIMEOUT
TARGET_WRITE_BROKEN_PIPE
TARGET_WRITE_CONNECTION_RESET_BY_PEER
TARGET_CONNECT_CONNECTION_REFUSED
Causa posible:
Este error se produce en uno de los siguientes casos:
La resolución de DNS incorrecta del host del servidor backend por parte del servidor de autorización personalizado ha provocado que las direcciones IP sean incorrectas, lo que ha derivado en errores de conexión.
Errores de tiempo de espera de conexión debido a:
La restricción del cortafuegos en el servidor backend impide que Apigee se conecte al servidor backend.
Problemas de conectividad de red entre Apigee y el servidor backend.
El host del servidor de destino especificado en el punto final de destino es incorrecto o tiene caracteres no deseados (como espacios).
Este error también puede producirse si el servidor backend cierra prematuramente la conexión mientras el procesador de mensajes sigue enviando la carga útil de la solicitud al servidor backend.
messaging.adaptors.http.flow.SslHandshakeFailed
Código de estado HTTP:
503 Service Unavailable
Mensaje de error:
SSL Handshake failed {error_message}
Causa posible:
Este error se produce durante el proceso de handshake SSL entre el procesador de mensajes de Apigee y el servidor backend si se da alguna de las siguientes circunstancias:
El almacén de confianza del procesador de mensajes de Apigee:
Contiene una cadena de certificados que no coincide con la cadena de certificados completa del servidor backend.
O
No contiene la cadena de certificados completa del servidor backend
La cadena de certificados presentada por el servidor backend:
Contiene un nombre de dominio completo que no coincide con el nombre de host especificado en el endpoint de destino.
O
Contiene una cadena de certificados incorrecta o incompleta
El servidor backend rechaza la versión de TLS que usa Apigee.
Por ejemplo, si el servidor backend solo acepta la versión 1.3 de TLS, pero el servidor de destino del lado de Apigee tiene la versión 1.2 de TLS definida en su campo TLS Protocol (o no tiene ninguna versión de TLS definida, en cuyo caso Apigee no usará la versión 1.3 de TLS de forma predeterminada), la conexión fallará debido a una discrepancia entre las versiones del protocolo.
Este error se produce en uno de los siguientes casos:
TargetServer no está configurado correctamente para admitir conexiones TLS/SSL
en Apigee.
El servidor backend puede cerrar la conexión de forma abrupta
mientras Apigee espera una respuesta del servidor backend.
Los tiempos de espera de Keep-Alive se han configurado de forma incorrecta en Apigee y en el servidor backend.
messaging.adaptors.http.flow.BadGateway
Código de estado HTTP:
502 Bad Gateway
Mensaje de error:
Bad Gateway
Causa posible:
Este error se produce si el servidor de destino envía una respuesta HTTP con formato incorrecto a Apigee.
messaging.runtime.*
messaging.runtime.RouteFailed
Código de estado HTTP:
500 Internal Server Error
Mensaje de error:
Unable to route the message to a TargetEndpoint
Causa posible:
Este error se produce si Apigee no puede enrutar la solicitud a ninguno de los
TargetEndpoints porque:
No hay ninguna condición de regla de ruta (<RouteRule>) que
coincida con la solicitud en un proxy
Y
No se ha definido ninguna regla de ruta predeterminada en ProxyEndpoint.
(es decir, <RouteRule> sin ninguna condición)
Solucionar
Para solucionar este error, siga estas instrucciones:
Revisa las reglas de ruta definidas en tu ProxyEndpoint y modifícalas para asegurarte de que haya al menos una condición de regla de ruta que coincida con tu solicitud.
Te recomendamos que definas una regla de ruta predeterminada sin ninguna condición
cuando tengas varias RouteRules.
Asegúrate de que la regla de ruta predeterminada siempre se defina en último lugar en la lista de rutas condicionales, ya que las reglas se evalúan de arriba abajo en ProxyEndpoint.
Para obtener más información sobre cómo definir <RouteRule> condiciones en un
ProxyEndpoint, consulte
Objetivos condicionales.
protocol.http.* - Caused due to bad request
protocol.http.BadFormData
Código de estado HTTP:
500 Internal Server Error
Mensaje de error:
Bad Form Data
Causa posible:
Este error se produce si y solo si se cumplen todas las condiciones siguientes:
La solicitud HTTP que envía el cliente a Apigee
contiene lo siguiente:
Content-Type: application/x-www-form-urlencoded,
y
Datos de formulario con el signo de porcentaje (%) o el signo de porcentaje (%) seguido de caracteres hexadecimales no válidos que no están permitidos según la
sección 17.13.4.1 de Formularios.
El proxy de API de Apigee lee los parámetros de formulario específicos que contienen caracteres no permitidos mediante la política ExtractVariables o AssignMessage en el flujo de solicitudes.
protocol.http.DuplicateHeader
Código de estado HTTP:
400 Bad Request
Mensaje de error:
Duplicate Header "{header_name}"
Causa posible:
Este error se produce si un encabezado HTTP específico que no puede tener duplicados en Apigee aparece más de una vez con el mismo valor o con valores diferentes como parte de la solicitud HTTP que la aplicación cliente envía a Apigee.
Asegúrate de que la solicitud HTTP que envía la aplicación cliente a Apigee siempre contenga un nombre de encabezado válido, tal como se indica en la
sección 3.2: Campos de encabezado del RFC 7230.
protocol.http.HeaderNameWithNonAsciiChar
Código de estado HTTP:
400 Bad Request
Mensaje de error:
Header {header_name} contains non ascii character {character}
Causa posible:
Este error se produce si el nombre del encabezado enviado como parte de la solicitud HTTP por la aplicación cliente a Apigee contiene caracteres no ASCII.
Asegúrate de que la solicitud HTTP del cliente enviada a Apigee no contenga caracteres que no sean ASCII en los nombres de los encabezados, tal como se indica en la
sección 3.2.6: Field Value Components del RFC 7230.
protocol.http.HeaderWithInvalidChar
Código de estado HTTP:
400 Bad Request
Mensaje de error:
Header {header_name} contains invalid character {character}
Causa posible:
Este error se produce si el nombre del encabezado enviado como parte de la solicitud HTTP por la aplicación cliente a Apigee contiene caracteres no válidos, como el signo igual (=), la coma (,), el punto y coma (;), la tabulación, CRLF y el carácter de salto de línea.
Asegúrate de que la solicitud HTTP que envía la aplicación cliente a Apigee no contenga caracteres no válidos en los nombres de los encabezados, tal como se indica en la
sección 3.2.6: Componentes de valor de campo del RFC 7230.
protocol.http.InvalidPath
Código de estado HTTP:
400 Bad Request
Mensaje de error:
Invalid path {path}
Causa posible:
Este error se produce si la ruta de la URL de la solicitud HTTP enviada por la aplicación cliente a Apigee contiene caracteres no permitidos según la especificación RFC 3986, sección 3.3: Ruta.
Asegúrate de que la ruta de la URL de la solicitud HTTP enviada por la aplicación cliente a Apigee no contenga ningún carácter no permitido, tal como se indica en la
sección 3.3: Ruta de RFC 3986.
protocol.http.MessageReadError
Código de estado HTTP:
502 Bad Gateway
Mensaje de error:
Unexpected I/O after message headers have been read.
Causa posible:
Este error poco frecuente se produce cuando el MP
recibe E/S en un canal cuando no lo espera. El MP está leyendo una solicitud, ha leído todos los encabezados y está configurado para leer la carga útil de la solicitud. Después, se produce un evento de E/S
que parece corresponder a los mismos encabezados.
Solucionar
Busca el mensaje de registro para obtener más información sobre lo que está ocurriendo.
logger.atSevere().log(
"Unexpected I/O after message headers have been read. Channel diagnostics=%s."
+ " HeartBeat=%s",
input.client().getDiagnostic(), message.getHeaders().isHeartBeat());
protocol.http.NoResolvedHost
Código de estado HTTP:
503 Service Unavailable
Mensaje de error:
Unable to resolve host {hostname}
Donde: {hostname} es dinámico y su valor
cambiará en función del nombre de host proporcionado.
Motivo:
TARGET_CONNECT_HOST_NOT_REACHABLE
Causa posible:
Este error se produce si el host del servidor de destino especificado es incorrecto o tiene caracteres no deseados (como un espacio).
protocol.http.TooBigBody
Código de estado HTTP:
413 Request Entity Too Large
Mensaje de error:
Body buffer overflow
Causa posible:
Este error se produce si el tamaño de la carga útil enviada por la aplicación cliente como parte de la solicitud HTTP a Apigee es superior al límite permitido en Apigee.
El tamaño total de todos los encabezados de solicitud enviados por la aplicación cliente como parte de la solicitud HTTP a Apigee es superior al límite permitido en Apigee.
Este error se produce si el tamaño de la línea de solicitud enviada por la aplicación cliente
como parte de la solicitud HTTP a Apigee es superior al límite permitido en
Apigee.
Este error se produce si el encabezado Content-Encoding enviado por el cliente como parte de la respuesta HTTP contiene un formato de codificación o de carga útil que no es compatible con Apigee.
Este error se produce si la URL de solicitud del servidor backend, representada por la variable de flujo target.url, contiene una ruta que empieza por un signo de interrogación (?) en lugar de una barra inclinada (/), lo que no es válido.
Este error se produce si el encabezado HTTP específico que no puede tener duplicados en Apigee aparece más de una vez con el mismo valor o con valores diferentes como parte de la respuesta HTTP que envía el servidor backend a Apigee.
Header {header_name} contains non ascii character {character}
Causa posible:
Este error se produce si el nombre del encabezado enviado por el servidor backend como parte de la respuesta HTTP a Apigee Edge contiene caracteres no ASCII.
Asegúrate de que la respuesta HTTP del servidor backend enviada a Apigee no contenga caracteres que no sean ASCII en los nombres de los encabezados, tal como se indica en la
sección 3.2.6: Field Value Components del RFC 7230.
protocol.http.HeaderWithInvalidChar
Código de estado HTTP:
502 Bad Gateway
Mensaje de error:
Header {header_name} contains invalid character {character}
Causa posible:
Este error se produce si el nombre del encabezado enviado por el servidor backend como parte de la respuesta HTTP contiene caracteres no válidos, como el signo igual (=), la coma (,), el punto y coma (;), la tabulación, CRLF y el carácter de salto de línea.
Proxy refused to create tunnel with response status {status code}
Causa posible:
Este error se produce durante la creación del túnel entre Apigee y el servidor backend por parte del servidor proxy debido a problemas con el cortafuegos, la lista de control de acceso (LCA), el DNS o la disponibilidad del servidor backend, entre otros.
Nota: El código de estado del mensaje de error
(faultstring) indica la causa general del problema.
protocol.http.Response306Reserved
Código de estado HTTP:
502 Bad Gateway
Mensaje de error:
Response Status code 306 is reserved, so can't be used.
Causa posible:
Este error se produce si el servidor backend responde a Apigee con el código de estado 306.
El código de estado 306 se definió en una versión anterior de la especificación HTTP. De acuerdo con la especificación HTTP actual, este código está reservado y no se debe usar.
Este error se produce si la respuesta HTTP del servidor backend a Apigee es 204 No Content o 205 Reset Content, pero contiene el cuerpo de la respuesta o uno o varios de los siguientes encabezados:
Este error se produce si el tamaño de la carga útil enviada por la aplicación cliente como parte de la solicitud HTTP a Apigee es superior al límite permitido en Apigee.
Este error se produce si el tamaño total de todos los encabezados de respuesta enviados por el servidor backend como parte de la respuesta HTTP a Apigee es superior al límite permitido en Apigee.
Este error se produce si el tamaño de la línea de respuesta enviada por el servidor backend como parte de la respuesta HTTP a Apigee es mayor que el límite permitido en Apigee Edge.
Este error se produce si la cabecera Content-Encoding enviada por el servidor backend como parte de la respuesta HTTP contiene el formato de codificación o de carga útil que no es compatible con Apigee.
KeyAlias {KeyAlias_name} is not found in
Keystore {Keystore_Name}
Causa posible:
Este error se produce si no se encuentra el KeyAlias específico al que se hace referencia en TargetEndpoint
o TargetServer en el Keystore específico.
Solucionar
Asegúrate de que el alias de clave especificado en TargetEndpoint o TargetServer exista y forme parte del almacén de claves específico.
security.util.TrustStoreWithNoCertificates
Código de estado HTTP:
500 Internal Server Error
Mensaje de error:
TrustStore {truststore_name} has no certificates
Causa posible:
Este error se produce si el almacén de confianza específico al que se hace referencia en TargetEndpoint o TargetServer no contiene ningún certificado.
Solucionar
Si quiere validar el certificado del servidor backend y usar el almacén de confianza en un TargetEndpoint o TargetServer, asegúrese de que el almacén de confianza contenga los certificados válidos del servidor backend.
[[["Es fácil de entender","easyToUnderstand","thumb-up"],["Me ofreció una solución al problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Es difícil de entender","hardToUnderstand","thumb-down"],["La información o el código de muestra no son correctos","incorrectInformationOrSampleCode","thumb-down"],["Me faltan las muestras o la información que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-11 (UTC)."],[],[],null,[]]
