Runtime error catalog

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Errors in Apigee Edge

When API requests are made through Apigee Edge, the Apigee Edge 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 Edge 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 414 Request-URI Too Long

An error response from the Message Processor appears in the following format: 

{
   "fault":{
      "faultstring":"request line size exceeding 7,168",
      "detail":{
         "errorcode":"protocol.http.TooBigLine"
      }
   }
}

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

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 Edge Message Processor component. It includes the following information for each of the error codes:

  • HTTP Status code
  • Error message
  • 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.

Note: This playbook provides instructions to troubleshoot the error code messaging.adaptors.http.flow.GatewayTimeout; however, you can use the same playbook to troubleshoot the flow.APITimedOut error code.

PLAYBOOK

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
PLAYBOOK

messaging.adaptors.http.flow

messaging.adaptors.http.flow.ApplicationNotFound
  • HTTP status code:
 404 Not Found
  • Error message:
 Unable to identify proxy for host: {virtual_host} and url: {pathsuffix}
  • Possible cause:

This error occurs under one of the following scenarios:

  1. The specific API Proxy is:
    1. NOT configured to accept requests on the specific Virtual Host
    2. NOT configured to accept requests on the specific path used in the request
    3. NOT deployed in the specific environment in which you are trying to make the API requests
    4. NOT deployed on one or more Message Processors
  2. The specific environment in which you are trying to make the API requests is not loaded on one or more Message Processors
 PLAYBOOK
This error can also occur if multiple virtual hosts have the same host alias and port number. PLAYBOOK

messaging.adaptors.http.flow.DecompressionFailureAtRequest
  • HTTP status code:
 400 Bad Request
  • Error message:
 Decompression failure at request
  • Possible cause:

This error occurs only if:

  • The encoding specified in the HTTP request header Content-Encoding is valid and supported by Apigee Edge,

    • 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
PLAYBOOK

messaging.adaptors.http.flow.DecompressionFailureAtResponse
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Decompression failure at response
  • 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 Edge,

    • 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
PLAYBOOK

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

PLAYBOOK

VIDEO

  • 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 Edge.
  • HTTP status code:
 503

PLAYBOOK

VIDEO

  • 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 Edge.
  • HTTP status code:
 504 PLAYBOOK
  • 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 Edge.

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 Edge 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, NGINX access logs, or analytics database.

messaging.adaptors.http.flow.GatewayTimeout
  • HTTP status code:
 504 Gateway Timeout
  • Error message:
 Gateway Timeout
  • Possible cause:
 This error occurs if the backend server doesn't respond back to the Apigee Edge Message Processor within the I/O timeout period configured on the Message Processor.
PLAYBOOK

messaging.adaptors.http.flow.LengthRequired
  • HTTP status code:
 411 Length Required
  • Error message:
 'Content-Length' is missing
  • 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 Edge.

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 Edge. 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
  • Possible cause:

This error occurs under one of the following scenarios, if you are using TargetServer in Apigee Edge:

  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 Edge from connecting to backend server.
    2. Network connectivity issues between Apigee Edge and backend server.
  3. The host specified in the TargetServer is incorrect or has unwanted characters (such as a space).

PLAYBOOK

VIDEO
This error can also occur if the health checks configured to monitor the health check of the target servers fail.

PLAYBOOK

VIDEO

messaging.adaptors.http.flow.RequestTimeOut
  • HTTP status code:
 408 Request Timeout
  • Error message:
 Request timed out
  • Possible cause:
 This error occurs if the Apigee Edge 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 Edge's Message Processor component.

messaging.adaptors.http.flow.ServiceUnavailable
  • HTTP status code:
 503 Service Unavailable
  • Error message:
 The Service is temporarily unavailable
  • 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 Edge from connecting to backend server.
    2. Network connectivity issues between Apigee Edge and backend server.
  3. The target server host specified in the Target Endpoint is incorrect or has unwanted characters (such as space).

PLAYBOOK

DNS failure:

VIDEO

Network connectivity:

VIDEO
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. PLAYBOOK

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 Edge’s Message Processor and the backend server if:

  1. The truststore of Apigee Edge’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

PLAYBOOK

VIDEO

messaging.adaptors.http.flow.UnexpectedEOFAtTarget
  • HTTP status code:
 502 Bad Gateway
  • Error message:
 Unexpected EOF at target
  • Possible cause:

This error occurs under one of the following scenarios:

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

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 Edge 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.

messaging.runtime.SenseRaiseFault
  • HTTP status code:
 403 Forbidden
  • Error message:
 Sense Fault
  • Possible cause:
 This error occurs if an API request is made from a particular client IP address which is blocked as part of the Apigee Sense rules.

Fix

To address this error, follow these instructions:

  1. Verify that you have blocked the specific client IP address by checking the rules configured in Apigee Sense. If it is blocked, then that indicates it is working as designed.
  2. If the specific client IP address is not blocked, but you are still getting this error, then contact Apigee Edge Support.

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 Edge 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 Edge reads the specific form parameters containing any characters that are not allowed using the ExtractVariables or the AssignMessage policy in the request flow.
PLAYBOOK

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 Edge, appears more than once with same or different values as part of the HTTP request sent by the client application to Apigee Edge.
  • HTTP Specification:
 RFC 7230, section 3.2.2: Field Order
PLAYBOOK

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 Edge is empty.
  • HTTP Specification:
 RFC 7230, section 3.2: Header Fields

Fix

Ensure that the HTTP request sent by the client application to Apigee Edge 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 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 client's HTTP request sent to Apigee Edge 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 Edge 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 Edge 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:
 This error occurs if the path in the HTTP request URL sent by the client application to Apigee Edge 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 Edge 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 Edge is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge is greater than the allowed limit in Apigee Edge.
  • HTTP Specification:
 RFC 6585, section 5: 431 Request Header Fields Too Large
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge.
  • HTTP Specification:
 RFC 7231, section 6.5.13: 415 Unsupported Media Type
PLAYBOOK

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
PLAYBOOK

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 Edge, appears more than once with same or different values as part of the HTTP response sent by the backend server to Apigee Edge.
  • HTTP Specification:
 RFC 7230, section 3.2.2: Field Order
PLAYBOOK

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 Edge is empty.
  • HTTP Specification:
 RFC 7230, section 3.2: Header Fields

Fix

Ensure that the HTTP response sent by the backend server to Apigee Edge 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
PLAYBOOK

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 Edge 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 Edge 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 Edge 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.
PLAYBOOK

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 Edge.

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 Edge.

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
PLAYBOOK

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 Edge 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
PLAYBOOK

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 Edge is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge is greater than the allowed limit in Apigee Edge.
  • Limits:
 Apigee Edge Limits
PLAYBOOK

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 Edge.
  • HTTP Specification:
 RFC 7231, section 6.5.13: 415 Unsupported Media Type
PLAYBOOK

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.