Runtime error catalog

This page applies to Apigee and 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

      • OR

    • With HTTP response sent by the backend server
  • 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:

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.

Error code Description Fix

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

    • OR

  • Exists but is not deployed

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,

    • BUT

  • 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

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,

    • BUT

  • 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

messaging.adaptors.http.flow.ErrorResponseCode
  • HTTP status code:
 500

  • Error message:
 Error Message and format can vary depending on the backend server implementation.
  • Possible cause:
 This error occurs if the backend server responds with status code 500 to Apigee.
  • HTTP status code:
 503
  • Error message:
 Error Message and format can vary depending on the backend server implementation.
  • Possible cause:
 This error occurs if the backend server responds with status code 503 to Apigee.
  • HTTP status code:
 504
  • Error message:
 Error Message and format can vary depending on the backend server implementation.
  • Possible cause:
 This error occurs if the backend server responds with status code 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:
 This error occurs if the backend server doesn't respond back to the Apigee Message Processor within the I/O timeout period configured on the Message Processor.

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:
 RFC Section 3.3.2: Content-Length

Fix

To address this error, perform the following steps:

  1. Ensure that the client application always passes the header Content-Length as part of the HTTP POST and PUT requests sent to Apigee. For example:

    curl -X POST https://HOSTALIAS/PATH -d '{"name": "abc"}' -H "Content-Length: 15"

  2. Even if you are passing an empty payload with POST and PUT requests, ensure that the header Content-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:

  1. The incorrect DNS resolution of the backend server host by custom authorization server resulted in bad IP addresses leading to connection errors.
  2. Connection timeout errors due to:
    1. Firewall restriction on the backend server prevents Apigee from connecting to backend server.
    2. Network connectivity issues between Apigee and backend server.
  3. The host specified in the TargetServer is incorrect or has unwanted characters (such as a space).
This error can also occur if the health checks configured to monitor the health check of the target servers fail.

messaging.adaptors.http.flow.RequestTimeOut
  • HTTP status code:
 408 Request Timeout
  • Error message:
 Request timed out
  • Reason:
 CLIENT_READ_TIMEOUT
  • Possible cause:
 This error occurs if the Apigee Message Processor doesn't receive the request payload from the client application for the I/O timeout period configured on the Message Processor component.

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:

  1. The incorrect DNS resolution of the backend server host by custom authorization server resulted in bad IP addresses leading to connection errors.
  2. Connection timeout errors due to:
    1. Firewall restriction on the backend server prevents Apigee from connecting to backend server.
    2. Network connectivity issues between Apigee and backend server.
  3. The target server host specified in the Target Endpoint is incorrect or has unwanted characters (such as space).
This error can also occur if the backend server prematurely closes the connection while the Message Processor is still sending the request payload to the backend server.

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:

  1. The truststore of Apigee's Message Processor:
    • Contains a certificate chain that does not match the backend server's complete certificate chain

      • OR

    • Does not contain the backend server's complete certificate chain
  2. 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

      • OR

    • Contains an incorrect/incomplete certificate chain

  3. 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:

  1. TargetServer is not properly configured to support TLS/SSL connections in Apigee.
  2. The backend server may close the connection abruptly, while Apigee is waiting for a response from the backend server.
  3. Keep alive timeouts configured incorrectly on Apigee and backend server.

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

    • AND

  • There is no default route rule defined in the ProxyEndpoint (i.e., <RouteRule> without any condition)

Fix

To address this error, follow these instructions:

  1. 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.
  2. It is a good practice to define a default route rule with no condition when you have multiple RouteRules.
  3. 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:

  1. 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.
  2. 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:
 This error occurs if a specific HTTP header that is not allowed to have duplicates in Apigee, appears more than once with same or different values as part of the HTTP request sent by the client application to Apigee.
  • HTTP Specification:
 RFC 7230, section 3.2.2: Field Order

protocol.http.EmptyHeaderName
  • HTTP status code:
 400 Bad Request
  • Error message:
 Header name cannot be empty
  • Possible cause:
 This error occurs if the header name sent as part of the HTTP request by the client application to Apigee is empty.
  • HTTP Specification:
 RFC 7230, section 3.2: Header Fields

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:
 This error occurs if the header name sent as part of the HTTP request by the client application to Apigee contains non-ASCII characters.
  • HTTP Specification:

RFC 7230, section 3.2: Header Fields and RFC 7230, section 3.2.6: Field Value Components

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:
 This error occurs if the header name sent as part of the HTTP request by the client application to Apigee contains invalid characters such as equal (=), comma (,), semicolon (;), tab, CRLF, and Newline character.
  • HTTP Specification:

RFC 7230, section 3.2: Header Fields and RFC 7230, section 3.2.6: Field Value Components

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.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:
 This error occurs if the target server host specified is incorrect or has unwanted characters (such as space).

protocol.http.InvalidPath
  • HTTP status code:
 400 Bad Request
  • Error message:
 Invalid path {path}
  • Possible cause:
 This error occurs if the path in the HTTP request URL sent by the client application to Apigee contains characters that are not permitted as per the specification RFC 3986, section 3.3: Path.
  • HTTP Specification:

RFC 3986, section 3: Syntax Components and RFC 3986, section 3.3: Path

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.TooBigBody
  • HTTP status code:
 413 Request Entity Too Large
  • Error message:
 Body buffer overflow
  • Possible cause:
 This error occurs if the payload size sent by the client application as part of HTTP request to Apigee is greater than the allowed limit in Apigee.
  • Limits:
 Apigee Limits

protocol.http.TooBigHeaders
  • HTTP status code:
 431 Request Header Fields Too Large
  • Error message:
 request headers size exceeding {limit}
  • Possible cause:
 The total size of all the request headers sent by the client application as part of the HTTP request to Apigee is greater than the allowed limit in Apigee.
  • HTTP Specification:
 RFC 6585, section 5: 431 Request Header Fields Too Large
  • Limits:
 Apigee Limits

protocol.http.TooBigLine
  • HTTP status code:
 414 Request-URI Too Long
  • Error message:
 request line size exceeding {limit}
  • Possible cause:
 This error occurs if the size of the request line sent by the client application as part of HTTP request to Apigee is greater than the allowed limit in Apigee.
  • Limits:
 Apigee Limits

protocol.http.UnsupportedEncoding
  • HTTP status code:
 415 Unsupported Media
  • Error message:
 Unsupported Encoding "{encoding}"
  • Possible cause:
 This error occurs if the 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:
 RFC 7231, section 6.5.13: 415 Unsupported Media Type

protocol.http.* - Caused by target

protocol.http.BadPath
  • HTTP status code:
 500 Internal Server Error
  • Error message:
 Invalid request path
  • Possible cause:
 This error occurs if the request URL of the backend server, represented by the flow variable target.url, contains a path that starts with a question mark (?) instead of a forward slash (/), which is invalid.
  • HTTP Specification:

RFC 3986, section 3: Syntax Components and RFC 3986, section 3.3: Path

protocol.http.DuplicateHeader
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Duplicate Header "{header_name}"
  • Possible cause:
 This error occurs if the specific HTTP header that is not allowed to have duplicates in Apigee, appears more than once with same or different values as part of the HTTP response sent by the backend server to Apigee.
  • HTTP Specification:
 RFC 7230, section 3.2.2: Field Order

protocol.http.EmptyHeaderName
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Header name cannot be empty
  • Possible cause:
 This error occurs if the header name sent by the backend server as part of the HTTP response to Apigee is empty.
  • HTTP Specification:
 RFC 7230, section 3.2: Header Fields

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:
 This error occurs if the HTTP request URL of the backend server, represented by the flow variable target.url, contains an empty path.
  • HTTP Specification:

RFC 3986, section 3: Syntax Components and RFC 3986, section 3.3: Path

protocol.http.HeaderNameWithNonAsciiChar
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Header {header_name} contains non ascii character {character}
  • Possible cause:
 This error occurs if the header name sent by the backend server as part of the HTTP response to Apigee Edge contains non-ASCII characters.
  • HTTP Specification:

RFC 7230, section 3.2: Header Fields and RFC 7230, section 3.2.6: Field Value Components

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:
 This error occurs if the header name sent by the backend server as part of the HTTP response, contains invalid characters such as equal (=), comma (,), semicolon (;), tab, CRLF, and Newline character.
  • HTTP Specification:

RFC 7230, section 3.2: Header Fields and RFC 7230, section 3.2.6: Field Value Components

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:
 RFC 7231, section 6.3.5: 306 Reserved

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:
 The backend server responds with 405 Method Not Allowed status code without the "Allow" header.
  • HTTP Specification:

RFC 7231, section 6.5.5: 405 Method Not Allowed and RFC 7231, section 7.4.1: Allow

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:

RFC 7231, section 6.3.5: 204 No Content and RFC 7231, section 6.3.6: 205 Reset Content

protocol.http.TooBigBody
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Body buffer overflow
  • Possible cause:
 This error occurs if the payload size sent by the client application as part of HTTP request to Apigee is greater than the allowed limit in Apigee.
  • Limits:
 Apigee Limits

protocol.http.TooBigHeaders
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 response headers size exceeding {limit}
  • Possible cause:
 This error occurs if the total size of all the response headers sent by the backend server as part of the HTTP response to Apigee is greater than the allowed limit in Apigee.
  • Limits:
 Apigee Limits

protocol.http.TooBigLine
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 response line size exceeding {limit}
  • Possible cause:
 This error occurs if the size of the response line sent by the backend server as part of HTTP response to Apigee is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Limits

protocol.http.UnsupportedEncoding
  • HTTP status code:
 415 Unsupported Media
  • Error message:
 Unsupported Encoding "{encoding}"
  • Possible cause:
 This error occurs if the 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:
 RFC 7231, section 6.5.13: 415 Unsupported Media Type

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.