Error response syntax

In most Akamai APIs, error responses in the 4xx-5xx range follow the RFC 7807 specification for Problem Details for HTTP APIs objects. This section summarizes what you're likely to find in your error response data to help diagnose the problem that led to the error.

  • status. If a status is provided, it reflects the same integer status code from the HTTP response bundled together with additional information about the error.

  • type. The error type uniquely identifies each distinct error case. Many different type values are possible for each error response code. For example, this error type from a 400 response in the Event Center API identifies an invalid range of start and end dates:

      "type": "/event-center/error-types/constraint-violation"
    

    Some type values appear as a short unique string such as constraint-violation, while others specify a longer URI path. Even fully qualified https URI values such as this one simply identify each problem, and are not navigable as URL links:

      "type": "https://problems.luna.akamaiapis.net/papi/v1/validation/validation_message.ssl_delegate_warning_rotate",
    
  • title. For each error type there's a corresponding title, a string that identifies the error. This makes it easier to recognize the error in a log file.

  • detail. The detail provides actionable instructions to diagnose the problem that caused the error. Some Akamai APIs provide all the instructions needed within this text, and others provide additional context in separate data members. The example below shows the field and value to identify the storage group you don't have sufficient permission to access.

  • instance. As its name suggests, the instance value is unique for each call to the API. If the detail doesn't help diagnose the problem, and if all else fails, you can pass along any provided instance value when you escalate to your technical support team.

  • errors. Some Akamai APIs are able to detect more than one problem in the request at a time. Those APIs provide details on each in a nested errors array. Objects in the array follow the same basic structure as the top-level object, but their type and detail values contain more fine-grained information.

This example shows an error response JSON body for the NetStorage Configuration API:

{
    "status": 400,
    "type": "validation-error",
    "title": "Validation failure",
    "detail": "Validation failed. Please review the errors.",
    "instance": "ea4afa39-29f1-4213-9d83-0a6b73a26edf",
    "errors": [
        {
            "type": "error-types/not.accessible",
            "title": "Not accessible",
            "detail": "You don't have permission to access the given storage group.",
            "field": "storageGroupId",
            "value": 123456
        }
    ]
}

👍

You can use Control Center or the Diagnostic Tools CLI to fetch a summary and log information for errors.


Did this page help you?