Error response customization (beta)
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
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).
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
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.