API gateway response codes

When an API is called, different HTTP status codes are returned by the gateway to indicate whether the request was successfully completed.

The response codes used in IBM® API Connect correspond to the registered HTTP status codes that are typically generated to provide informational (1xx), successful (2xx), redirection (3xx), client error (4xx), or server error (5xx) responses, as described at https://tools.ietf.org/html/rfc7231#section-6 and Hypertext Transfer Protocol (HTTP) Status Code Registry.

In API Connect, successful responses vary depending on the API being called. Other response codes can also be generated, depending on the implementation of the assembly and the response from the external systems. The standard reasons listed for the registered HTTP status codes are considered adequate for most responses that are returned; these response codes and their causes are therefore not listed here.

In certain cases, a client or server error response code can be caused by a condition that is specific to API Connect. The following table contains a list of these error response codes and identifies possible causes for these codes being returned. For some error codes, multiple causes are possible.

Table 1. Error codes and their causes
Error Code Cause
401 Unauthorized
  • The required client identification has not been successfully provided.
  • User authentication failed or did not take place.
403 Forbidden
  • The application is not registered with the plan that is used.
  • The application is not active.
  • User authentication failed because multiple client IDs provided.
404 Not Found
  • Information for the provider organization or environment was not found.
  • The API URL was not found in the organization or environment.
405 Method Not Allowed The API URL was found, but no operation was found that supports the requested HTTP verb.
406 Not Acceptable The API cannot produce any responses that are supported by the application.
429 Too Many Requests The rate limit has been exceeded for the plan or operation being used.
500 Internal Server Error An error occurred while executing this request.
503 Service Unavailable The status of an API was switched from online to offline, making the API unavailable across all Products in which it is contained.

For more information, see Managing your Products in the API Manager UI and Managing API Products using the developer toolkit.