This page applies to Apigeeand Apigee hybrid.
View Apigee Edge
documentation.
Errors in Apigee
When API requests are made through Apigee, the Apigee components Routers and Message Processors, or the backend servers can return errors to the client applications.
Errors from Message Processor
The Message Processor is the core component of Apigee that processes the policies and interacts with the backend servers. It can return errors if it detects any issues such as:
- Network connectivity issues, TLS handshake failures, unavailability of backend server, lack of response during communication with the backend server
- Failures during policy execution
- Invalid HTTP headers, encoding, path, non-adherence to HTTP specifications, exceeding
product limits, etc.:
- With HTTP request sent by the client applications
- With HTTP response sent by the backend server
OR
- And many more
Sample error from Message Processor
The Message Processor always returns an HTTP status code followed by an error message along with an error code in JSON format as shown below:
The client application gets a response code like the following example:
HTTP/1.1 504 Gateway Timeout
An error response from the Message Processor appears in the following format:
{ "fault": { "faultstring": "Gateway Timeout", "detail": { "errorcode": "messaging.adaptors.http.flow.GatewayTimeout" "reason": "TARGET_READ_TIMEOUT" } } }
Description of the fields in the error response:
Field | Description |
---|---|
faultstring
|
Contains the error message describing the possible cause for the error |
errorcode
|
Error code (also referred as fault code) associated with the error |
reason
|
Contains a message indicating the possible reason for the error |
Runtime error catalog
This error catalog provides all the information that you need to know about the runtime error codes(for non-policy errors) that are returned by the Apigee Message Processor component. It includes the following information for each of the error codes:
- HTTP Status code
- Error message
- Reason for the error (not all error messages display a
reason
) - Possible causes for the error
- Any associated HTTP specifications and/or product limits
- Playbooks and videos that contain instructions to diagnose the cause of the error and effective solutions that you can apply to resolve the error yourself (where available)
- Fix that you can apply to resolve the error yourself
The following error code categories are covered:
- flow.*
- messaging.adaptors.http.flow.*
- messaging.runtime.*
- protocol.http.* - request
- protocol.http.* - target
- security.util.*
Use the Search box below to filter the table to display the above information for a specific error code. You can search for the status code or any content in any field in the table.
Search
flow.*
flow.APITimedOut
- HTTP status code:
504 Gateway Timeout
- Error message:
API timed out
- Possible cause:
This error occurs if:
- The backend server doesn't respond back within the timeout period configured
by the property
api.timeout
for the specific API Proxy. - A policy takes a long time due to computationally intensive operations, high load, or poor performance.
flow.SharedFlowNotFound
- HTTP status code:
500 Internal Server Error
- Error message:
Shared Flow {shared_flow_name} Not Found
- Possible cause:
This error occurs if the specific shared flow:
- Does not exist
- Exists but is not deployed
OR
messaging.adaptors.http.flow
messaging.adaptors.http.flow.DecompressionFailureAtRequest
- HTTP status code:
400 Bad Request
- Error message:
Decompression failure at request
- Reason:
CLIENT_READ_CONTENT_NOT_IN_GZIP_FORMAT
- Possible cause:
This error occurs only if:
- The encoding specified in the HTTP request header
Content-Encoding
is valid and supported by Apigee, - The payload format sent by the client as part of the HTTP
request does not match the encoding format specified in the
Content-Encoding
header
BUT
messaging.adaptors.http.flow.DecompressionFailureAtResponse
- HTTP status code:
502 Bad Gateway
- Error message:
Decompression failure at response
- Reason:
TARGET_READ_CONTENT_NOT_IN_GZIP_FORMAT
TARGET_READ_INCORRECT_HEADER_CHECK
- Possible cause:
This error occurs only if:
- The encoding specified in the backend/target server's
HTTP response header
Content-Encoding
is valid and supported by Apigee, - The payload format sent by the backend/target server as
part of the HTTP response does not match the encoding format specified in the
Content-Encoding
header
BUT
messaging.adaptors.http.flow.ErrorResponseCode
- HTTP status code:
500
- Error message:
- Possible cause:
500
to Apigee.- HTTP status code:
503
- Error message:
- Possible cause:
503
to Apigee.- HTTP status code:
504
- Error message:
- Possible cause:
504
to Apigee. Note:
The error code messaging.adaptors.http.flow.ErrorResponseCode
is not returned
as part of the error message sent to the client applications. This is
because this error code is set by Apigee whenever the backend server
responds with an error and any of the 4XX
or 5XX
status codes. You can view this error code in API Monitoring
or analytics database.
messaging.adaptors.http.flow.GatewayTimeout
- HTTP status code:
504 Gateway Timeout
- Error message:
Gateway Timeout
- Reason:
TARGET_READ_TIMEOUT
- Possible cause:
messaging.adaptors.http.flow.InternalServerError
- HTTP status code:
500 Internal Server Error
- Error message:
Internal server error at backend
- Reason:
SERVER_ERROR
- Possible cause:
- The backend application encountered an unhandled exception or error while processing the request from Apigee. This might stem from issues such as faulty logic, unexpected input, or other runtime problems within the application code.
- The backend server might have failed to connect to its database, or a database query might have failed. This can happen due to network connectivity, incorrect database credentials, database server downtime, or issues with the database schema or data.
- If your backend server depends on other internal or external services, such as APIs, message queues, or caching systems, a failure in one of these dependencies can cause it to return a
500
error to Apigee. The backend might be unable to communicate with the dependent service or might receive error responses from it. - The backend server might be overloaded due to high traffic, insufficient memory (RAM), excessive CPU utilization, or low disk space. When the server lacks adequate resources, it can't process requests and responds with a
500
error. - Incorrect settings on the backend server can cause unexpected errors during request processing. This includes issues with server configurations, application settings, or deployment configurations.
- There might be an underlying bug in the backend application code that is triggered by the specific request from Apigee. These bugs might not be apparent under normal circumstances but are exposed by certain request patterns or data.
messaging.adaptors.http.flow.LengthRequired
- HTTP status code:
411 Length Required
- Error message:
'Content-Length' is missing
- Reason:
CLIENT_REQUEST_CONTENT_LENGTH_REQUIRED
- Possible cause:
This error occurs if the Content-Length
header is not passed by
the client application as part of the HTTP POST
and PUT
requests sent to Apigee.
Note: The requests failing with this error cannot be captured in the Trace tool, since the Message Processor performs this validation in a very early phase, much before processing the request and executing any policy in the API Proxy.
- HTTP Specification:
Fix
To address this error, perform the following steps:
-
Ensure that the client application always passes the header
Content-Length
as part of the HTTPPOST
andPUT
requests sent to Apigee. For example:curl -X POST https:// HOSTALIAS / PATH -d '{"name": "abc"}' -H "Content-Length: 15"
-
Even if you are passing an empty payload with
POST
andPUT
requests, ensure that the headerContent-Length: 0
is passed. For example:curl -X POST https:// HOSTALIAS / PATH -H "Content-Length: 0"
messaging.adaptors.http.flow.NoActiveTargets
- HTTP status code:
503 Service Unavailable
- Error message:
The Service is temporarily unavailable
- Reason:
TARGET_HEALTHCHECK_CONNECT_TIMEOUT
TARGET_HEALTHCHECK_CONNECTION_REFUSED
TARGET_HEALTHCHECK_HTTPS_REQUEST_OVER_HTTP
TARGET_HEALTHCHECK_UNEXPECTED_EOF
- Possible cause:
This error occurs under one of the following scenarios, if you are using TargetServer in Apigee:
- The incorrect DNS resolution of the backend server host by custom authorization server resulted in bad IP addresses leading to connection errors.
- Connection timeout errors due to:
- Firewall restriction on the backend server prevents Apigee from connecting to backend server.
- Network connectivity issues between Apigee and backend server.
- The host specified in the TargetServer is incorrect or has unwanted characters (such as a space).
messaging.adaptors.http.flow.RequestTimeOut
- HTTP status code:
408 Request Timeout
- Error message:
Request timed out
- Reason:
CLIENT_READ_TIMEOUT
- Possible cause:
Fix
Ensure that the client application sends the request payload within the I/O timeout period configured on the Apigee's Message Processor component.
messaging.adaptors.http.flow.ServiceUnavailable
- HTTP status code:
503 Service Unavailable
- Error message:
The Service is temporarily unavailable
- Reason:
TARGET_CONNECT_TIMEOUT
TARGET_WRITE_BROKEN_PIPE
TARGET_WRITE_CONNECTION_RESET_BY_PEER
TARGET_CONNECT_CONNECTION_REFUSED
- Possible cause:
This error occurs under one of the following scenarios:
- The incorrect DNS resolution of the backend server host by custom authorization server resulted in bad IP addresses leading to connection errors.
- Connection timeout errors due to:
- Firewall restriction on the backend server prevents Apigee from connecting to backend server.
- Network connectivity issues between Apigee and backend server.
- The target server host specified in the Target Endpoint is incorrect or has unwanted characters (such as space).
messaging.adaptors.http.flow.SslHandshakeFailed
- HTTP status code:
503 Service Unavailable
- Error message:
SSL Handshake failed {error_message}
- Possible cause:
This error occurs during the SSL handshake process between Apigee's Message Processor and the backend server if:
- The truststore of Apigee's Message Processor:
- Contains a certificate chain that does not match the backend server's complete certificate chain
- Does not contain the backend server's complete certificate chain
OR
- The certificate chain presented by the backend server:
- Contains a Fully Qualified Domain Name (FQDN) that does not match the host name specified in the target endpoint
- Contains an incorrect/incomplete certificate chain
OR
-
The backend server rejects the TLS version used by Apigee.
For example, if the backend server accepts only TLS version 1.3, but the target server on the Apigee side has TLS version 1.2 set in its
TLS Protocol
field (or no TLS version is set at all, in which case Apigee will currently not use TLS version 1.3 as a default), the connection fails due to a mismatch of protocol versions.
messaging.adaptors.http.flow.UnexpectedEOFAtTarget
- HTTP status code:
502 Bad Gateway
- Error message:
Unexpected EOF at target
- Reason:
TARGET_READ_UNEXPECTED_EOF
- Possible cause:
This error occurs under one of the following scenarios:
- TargetServer is not properly configured to support TLS/SSL connections in Apigee.
- The backend server may close the connection abruptly, while Apigee is waiting for a response from the backend server.
- Keep alive timeouts configured incorrectly on Apigee and backend server.
messaging.adaptors.http.flow.BadGateway
- HTTP status code:
502 Bad Gateway
- Error message:
Bad Gateway
- Possible cause:
This error occurs if the target server sends a malformed HTTP response back to Apigee.
messaging.runtime.*
messaging.runtime.RouteFailed
- HTTP status code:
500 Internal Server Error
- Error message:
Unable to route the message to a TargetEndpoint
- Possible cause:
This error occurs if Apigee cannot route the request to any of the TargetEndpoints because:
- There is no route rule (
<RouteRule>
) condition that matches the request in a proxy - There is no default route rule defined in the ProxyEndpoint
(i.e.,
<RouteRule>
without any condition)
AND
Fix
To address this error, follow these instructions:
- Review the route rules defined in your ProxyEndpoint and modify to ensure that there is at least one route rule condition that matches your request.
- It is a good practice to define a default route rule with no condition when you have multiple RouteRules.
- Ensure that the default route rule is always defined last in the list of conditional Routes because rules are evaluated top-down in the ProxyEndpoint.
To learn more about defining <RouteRule>
conditions in a
ProxyEndpoint, see Conditional Targets
.
protocol.http.* - Caused due to bad request
protocol.http.BadFormData
- HTTP status code:
500 Internal Server Error
- Error message:
Bad Form Data
- Possible cause:
This error occurs if and only if all of the following conditions are met:
- The HTTP request sent by the client to Apigee
contains:
-
Content-Type: application/x-www-form-urlencoded
, and - Form data with the percent sign (%), or the percent sign (%) followed by invalid hexadecimal characters that are not allowed as per Forms - Section 17.13.4.1 .
-
- The API proxy in Apigee reads the specific form parameters containing any characters that are not allowed using the ExtractVariables or the AssignMessage policy in the request flow.
protocol.http.DuplicateHeader
- HTTP status code:
400 Bad Request
- Error message:
Duplicate Header "{header_name}"
- Possible cause:
- HTTP Specification:
protocol.http.EmptyHeaderName
- HTTP status code:
400 Bad Request
- Error message:
Header name cannot be empty
- Possible cause:
- HTTP Specification:
Fix
Ensure that the HTTP request sent by the client application to Apigee always contains a valid header name as per RFC 7230, section 3.2: Header Fields .
protocol.http.HeaderNameWithNonAsciiChar
- HTTP status code:
400 Bad Request
- Error message:
Header {header_name} contains non ascii character {character}
- Possible cause:
- HTTP Specification:
Fix
Ensure that the client's HTTP request sent to Apigee doesn't contain non-ASCII characters in header names as per RFC 7230, section 3.2.6: Field Value Components .
protocol.http.HeaderWithInvalidChar
- HTTP status code:
400 Bad Request
- Error message:
Header {header_name} contains invalid character {character}
- Possible cause:
- HTTP Specification:
Fix
Ensure that the HTTP request sent by the client application to Apigee doesn't contain any invalid characters in the header names as per RFC 7230, section 3.2.6: Field Value Components
protocol.http.InvalidPath
- HTTP status code:
400 Bad Request
- Error message:
Invalid path {path}
- Possible cause:
- HTTP Specification:
Fix
Ensure that the path in the HTTP request URL sent by the client application to Apigee does not contain any characters that are not permitted as per RFC 3986, section 3.3: Path .
protocol.http.MessageReadError
- HTTP status code:
502 Bad Gateway
- Error message:
Unexpected I/O after message headers have been read.
- Possible cause:
Fix
Locate the log message for more information on what is happening.
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
- HTTP status code:
503 Service Unavailable
- Error message:
Unable to resolve host {hostname}
Where: {hostname}
is dynamic and its value
will change with respect to the host name provided.
- Reason:
TARGET_CONNECT_HOST_NOT_REACHABLE
- Possible cause:
protocol.http.TooBigBody
- HTTP status code:
413 Request Entity Too Large
- Error message:
Body buffer overflow
- Possible cause:
- Limits:
protocol.http.TooBigHeaders
- HTTP status code:
431 Request Header Fields Too Large
- Error message:
request headers size exceeding {limit}
- Possible cause:
- HTTP Specification:
- Limits:
protocol.http.TooBigLine
- HTTP status code:
414 Request-URI Too Long
- Error message:
request line size exceeding {limit}
- Possible cause:
- Limits:
protocol.http.UnsupportedEncoding
- HTTP status code:
415 Unsupported Media
- Error message:
Unsupported Encoding "{encoding}"
- Possible cause:
Content-Encoding
header sent by the client
as part of the HTTP response contains an encoding/payload format that is not
supported by Apigee.- HTTP Specification:
protocol.http.* - Caused by target
protocol.http.BadPath
- HTTP status code:
500 Internal Server Error
- Error message:
Invalid request path
- Possible cause:
- HTTP Specification:
protocol.http.DuplicateHeader
- HTTP status code:
502 Bad Gateway
- Error message:
Duplicate Header "{header_name}"
- Possible cause:
- HTTP Specification:
protocol.http.EmptyHeaderName
- HTTP status code:
502 Bad Gateway
- Error message:
Header name cannot be empty
- Possible cause:
- HTTP Specification:
Fix
Ensure that the HTTP response sent by the backend server to Apigee always contains a valid header name as per RFC 7230, section 3.2: Header Fields .
protocol.http.EmptyPath
- HTTP status code:
500 Internal Server Error
- Error message:
Request path cannot be empty
- Possible cause:
- HTTP Specification:
protocol.http.HeaderNameWithNonAsciiChar
- HTTP status code:
502 Bad Gateway
- Error message:
Header {header_name} contains non ascii character {character}
- Possible cause:
- HTTP Specification:
Fix
Ensure that the backend server's HTTP response sent to Apigee doesn't contain non-ASCII characters in header names as per RFC 7230, section 3.2.6: Field Value Components .
protocol.http.HeaderWithInvalidChar
- HTTP status code:
502 Bad Gateway
- Error message:
Header {header_name} contains invalid character {character}
- Possible cause:
- HTTP Specification:
Fix
Ensure that the backend server's HTTP response sent to Apigee doesn't contain any invalid characters in the header names as per RFC 7230, section 3.2.6: Field Value Components
protocol.http.ProxyTunnelCreationFailed
- HTTP status code:
503 Service Unavailable
- Error message:
Proxy refused to create tunnel with response status {status code}
- Possible cause:
This error occurs during the creation of the tunnel between Apigee and the backend server by the proxy server due to firewall, ACL (Access Control List), DNS issues, availability of backend server's availability, etc.
Note:
The status code
in the error message
( faultstring
) provides the high-level cause of the issue.
protocol.http.Response306Reserved
- HTTP status code:
502 Bad Gateway
- Error message:
Response Status code 306 is reserved, so can't be used.
- Possible cause:
This error occurs if the backend server responded back with 306
status code to Apigee.
The 306
status code was defined in a previous version of the
HTTP specification. As per the current HTTP specification, this code is
reserved and should not be used.
- HTTP Specification:
Fix
Since the status code 306
is reserved, ensure that
your backend server does not use this status code while sending a
response to Apigee.
protocol.http.Response405WithoutAllowHeader
- HTTP status code:
502 Bad Gateway
- Error message:
Received 405 Response without Allow Header
- Possible cause:
405 Method Not Allowed
status code without the "Allow"
header.- HTTP Specification:
protocol.http.ResponseWithBody
- HTTP status code:
502 Bad Gateway
- Error message:
Received {status_code} Response with message body
- Possible cause:
This error occurs if the HTTP response from the backend server to Apigee is
either 204 No Content
or 205 Reset Content
but it contains the
response body and/or one or more of the following headers:
-
Content-Length
-
Content-Encoding
-
Transfer-Encoding
- HTTP Specification:
protocol.http.TooBigBody
- HTTP status code:
502 Bad Gateway
- Error message:
Body buffer overflow
- Possible cause:
- Limits:
protocol.http.TooBigHeaders
- HTTP status code:
502 Bad Gateway
- Error message:
response headers size exceeding {limit}
- Possible cause:
- Limits:
protocol.http.TooBigLine
- HTTP status code:
502 Bad Gateway
- Error message:
response line size exceeding {limit}
- Possible cause:
- Limits:
protocol.http.UnsupportedEncoding
- HTTP status code:
415 Unsupported Media
- Error message:
Unsupported Encoding "{encoding}"
- Possible cause:
Content-Encoding
header sent by the
backend server as part of the HTTP response contains the encoding/payload
format that is not supported by Apigee.- HTTP Specification:
security.util.*
security.util.KeyAliasNotFound
- HTTP status code:
500 Internal Server Error
- Error message:
KeyAlias {KeyAlias_name} is not found in
Keystore {Keystore_Name}
- Possible cause:
This error occurs if the specific KeyAlias referenced in the TargetEndpoint or TargetServer is not found in the specific Keystore.
Fix
Ensure that the KeyAlias specified in the TargetEndpoint or TargetServer exists and is part of the specific Keystore.
security.util.TrustStoreWithNoCertificates
- HTTP status code:
500 Internal Server Error
- Error message:
TrustStore {truststore_name} has no certificates
- Possible cause:
This error occurs if the specific Truststore referenced in the TargetEndpoint or TargetServer doesn't contain any certificates.
Fix
If you would like to validate the backend server's certificate and want to use the Truststore in a TargetEndpoint or TargetServer, then ensure that the Truststore contains the backend server's valid certificates.