Troubleshooting

API errors in the Edge Network API can have a variety of causes, internal (Edge Network itself) or external (input, configuration, or upstream related). This page explains how the API reports errors, how to interpret them, and when to retry a request. For a complete list of error codes and the recommended action for each, see Error codes.

Error responses include a request ID (requestId). Include this value whenever you contact Adobe Customer Care about an error.

Error categories

Error severity

Edge Network API errors are also split by severity. Severity determines whether the Edge Network finished processing your request, and how the error is returned.

Request processing, input, configuration, authorization, and geographic restriction errors are fatal. Upstream errors are non-fatal.

Fatal errors

Fatal errors halt request processing and return a non-2xx HTTP status. See Retry strategy to learn which status codes you can retry.

The response body contains a problem detail, as defined by RFC 7807 Problem Details for HTTP APIs. The returned content type is application/problem+json. This response contains machine-readable details about the error, including a URI type.

All error objects have type, status, title, detail, and report properties, so that the API client can tell what the problem is.

{
   "type":"https://ns.adobe.com/aep/errors/EXEG-0104-422",
   "status":422,
   "title":"Unprocessable entity",
   "detail":"Invalid request (report attached). Please check your input and try again.",
   "report":{
      "errors":[
         "Allowed Adobe version is 1.0 for standard 'Adobe' at index 0",
         "Allowed IAB version is 2.0 for standard 'IAB TCF' at index 1",
         "IAB consent string value must not be empty for standard 'IAB TCF' at index 1"
      ],
      "requestId":"0f8821e5-ed1a-4301-b445-5f336fb50ee8",
      "orgId":"53A16ACB5CC1D3760A495C99@AdobeOrg"
   }
}

Non-fatal errors

Non-fatal errors occur when the Edge Network accepts your request, but one or more upstream services encounter an error while processing it. Unlike fatal errors, non-fatal errors don't halt the request. The response uses the standard application/json format, and the HTTP status of the response is 207 Multi-Status.

Each non-fatal error appears as an object in the errors array of the response body, using the same problem detail format as fatal errors. The status property of each error object reflects the specific upstream failure, such as 504 for a timeout or 502 for a bad gateway. This value is distinct from the 207 HTTP status of the response, so inspect the response body to understand what happened.

The following example shows a 207 Multi-Status response for a request where the Adobe Target upstream timed out:

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errors": [
    {
      "type": "https://ns.adobe.com/aep/errors/EXEG-0200-504",
      "status": 504,
      "title": "The service call has timed out",
      "detail": "The service call to com.adobe.target exceeded the allowed time and was canceled.",
      "report": {
        "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ]
}

Non-fatal errors only affect the real-time response capabilities of a request, such as personalization decisions or offers. The following upstream services can fail non-fatally. Error messages refer to these services by their service ID, in place of the {serviceName} placeholder.

Data collection is not affected by non-fatal errors. If the Edge Network accepts your request, your event data is collected for the following services, regardless of any non-fatal errors in the response:

• Adobe Experience Platform, including Real-Time Customer Data Platform and downstream applications
• Adobe Analytics
• Server-side forwarding

data-variant=warning

data-slots=text

Warnings

Warnings are mostly informative. They generally represent a potentially transient condition that did not fully impact the request. One example is a partial profile read in the segmentation engine. In this case, the accuracy is impacted to some degree, but the functionality is still delivered.

Warnings appear in the warnings array of the response body, using the same problem detail format as errors. A response that contains only warnings returns HTTP status 200, and each warning has a status of 200. If the response also contains non-fatal errors, the HTTP status of the response is 207 Multi-Status.

The following error codes are returned as warnings: EXEG-0204-200, EXEG-0301-200, and EXEG-0303-200.

{
  "requestId": "72eaa048-207e-4dde-bf16-0cb2b21336d5",
  "handle": [
  ],
  "warnings": [
    {
      "type": "https://ns.adobe.com/aep/errors/EXEG-0204-200",
      "status": 200,
      "title": "A warning occurred while calling the 'com.adobe.audiencemanager' service for this request.",
      "report": {
        "cause": {
          "message": "Cannot read related customer for device id: ...",
          "code": 202
        }
      }
    }
  ]
}

Retry strategy

Base your retry decisions on the HTTP status of the response, not on the status property of individual objects in the errors array. For example, a 207 Multi-Status response can contain an error object with a status of 504, but you should not retry that request.

Exponential backoff

When you retry 502, 503, or 504 errors, use exponential backoff with the following parameters:

With these parameters, the delays between attempts are 1, 2, 4, 8, 16, 32, 60, and 60 seconds. If the error persists for more than 10 minutes, contact Adobe Customer Care and include the requestId.

Detailed error codes list

See Error codes for the complete list of Edge Network API error codes. Each entry includes the error message, a description, whether the error is retriable, and the recommended action.