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.
For details on API throttling, see API throttling.

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

📘

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.

You can customize this error message in the API Keys and Traffic Management app when defining a throttling counter.

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

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.

Customize error responses

To help your users better understand the error messages they may potentially encounter while making requests to your registered APIs, you can customize the response bodies, status codes, and headers of selected errors.

📘

API

You can also complete this task by using the API Endpoints API. Run the Edit error response settings and Edit an error response operations. Learn more about Akamai's APIs.

1. On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration you want to customize error responses for.

2. From the menu, select Manage versions.

3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version you want to customize error responses for.

4. From the list of delivery options, select Error response customization.

5. On the Error response customization page, find an error response that you want to customize.
   For error descriptions, see Error response customization.

6. Set the Override default response switch for that response to Yes.

7. In the Status code field, enter the status code to be associated with the response.
   For guidance on status codes, see status code definitions.

8. In the Body field, enter the description that you want to return in case of the error.

📘

Ensure that the format of the description properly reflects the content-type. For example, in case of a JSON body format, enclose the text in curly brackets ({}).

9. In the Headers section, specify the Content-Typeheader to match the content-type of the response.

10. Optional: Click the plus sign to specify an additional header to be included in the response.

11. Click Save.