Error response customization (beta)

If an inbound client request fails API Gateway validation, the client receives an error response with a default description of an error in a JSON format and a default status code. For selected errors, you have an option to customize these details. For example, you can include in a response helpful guidelines on how to resolve a particular error and set a status code that more aptly reflects the nature of an error.

You can customize responses related to the following errors:

API key invalid
The API key in the incoming request does not exist in API Keys and Traffic Management. The default status code for this error is 401. You may advise API consumers to verify the API key in their request.
API key forbidden
The API key in the incoming request does not have access to the requested resource. The default status code for this error is 403. You may advise API consumers to verify the API key in their request.
Note: You decide which keys have access to which resources in API Keys and Traffic Management.
Quota exceeded
The quota limit for a particular API key included in the incoming request has been exceeded during the current time period. The default status code for this error is 429. You may advise API consumers to wait for the quota to reset and retry the request. To provide additional information on the limit set on a particular API key and the time of the next quota reset, you can enable the following quota-related headers: X-RateLimit-Limit and X-RateLimit-Next. For details, see User quota.
JWT signature invalid
The JSON web signature in JWT did not pass the JWT validation. This is usually caused by a failed RSA key verification. The default status code for this error is 401. You may advise API consumers to upload the latest public RSA key that corresponds to the private key used to create the signature.
JWT claim value invalid
The JWT claim value did not pass the validation. The default status code for this error is 401. You may advise API consumers to ensure the failed JWT claim contains a value that meets the validation criteria.
API throttling limit reached
The requests-per-second throttling limit associated with a throttling counter has been reached. The default status code for this error is 429. You can advise API consumers to wait for up to ten seconds and try to resend a request. You can customize this error message in the API Keys and Traffic Management app when defining a throttling counter. For details on API throttling, see API throttling (beta).

Headers

By default, the error responses that API Gateway returns are in a JSON format. If desired, you may return messages in a different format, for example, XML. In such case, you also need to set the Content-Type header for a particular error to an appropriate value (for the XML example, the value could be application/problem+xml).

You can also tell API Gateway to return custom headers. These may be useful for troubleshooting or providing additional information about an error. For example, the Request-ID custom header may include a unique identifier by which you can easily trace out requests.