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

Error types

Error	Type	Description	Status code
`RequestProcessingError`	Internal	General purpose error issued by the Adobe Experience Platform Edge Network on unexpected circumstances.	`500`
`InputError`	External	Includes errors caused by malformed input, as well as entity validation errors.	`4xx`
`ConfigurationError`	External	Server-side configuration errors.	`422`
`UpstreamError`	External	Communication errors with upstream services.	`207 Multi-Status`

Severity

Edge Network API errors can also be split by severity:

Fatal errors halt the dispatch pipeline.
Non-fatal errors could signal a partial processing, while allowing for request processing to continue. When present, the overall status code of the request becomes 207 Multi-Status.

Error	Type	Remarks
`RequestProcessingError`	Fatal	Can happen at any point during request processing.
`InputError`	Fatal	Happens when accepting the request, before dispatching it upstream.
`ConfigurationError`	Fatal	Happens when accepting the request, before dispatching it upstream.
`UpstreamError`	Non-Fatal	Communication errors with upstream services.

Fatal errors

Fatal errors halt the request processing and cause a non-2xx response status to be returned. See the error types section to see the expected status code, corresponding to each error type.

Errors are accompanied by a response body containing an error object. In this case, the response body contains a problem detail, as defined by RFC 7807 Problem Details for HTTP APIs.

The returned content-type is the application/problem+json media type. When present, this response contains machine-readable details pertaining to the error. Problem details include a URI type.

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

Property	Type	Description
`type`	String	A URI reference (RFC3986) that identifies the problem type, following the format `https://ns.adobe.com/aep/errors/<ERROR-CODE>`.
`status`	Number	The HTTP status code generated by the server for this occurrence of the problem.
`title`	String	A short, human-readable summary of the problem type.
`detail`	String	A short, human-readable description of the problem type.
`report`	Object	A map of additional properties that aid in debugging such as the request ID or the org ID. In some cases, it might contain data specific to the error at hand, such as a list of validation errors.

{
   "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"
   }
}
Copied to your clipboard
{
   "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 can be further broken down into:

Errors: Issues that occurred while processing the request, but did not cause the entire request to be rejected (eg. a non-critical upstream failure).
Warnings: Messages from upstream services which could signal that a partial processing of the request occurred.

When encountering non-fatal errors (excluding warnings), the API changes the response status to 207 Multi-Status.

Warnings, on the other hand, are mostly informative, as they generally represent a potentially transient condition, which did not impact the request to full extent. One example here is a partial profile read in the segmentation engine, in which case the accuracy is impacted to some degree, but the functionality is still delivered.

Non-fatal errors are represented in the Problem Details format, but are embedded directly in the gateway's standard response, which is of type application/json.

{
  "requestId": "72eaa048-207e-4dde-bf16-0cb2b21336d5",
  "handle": [
  ],
  "errors": [
    {
      "type": "https://ns.adobe.com/aep/errors/EXEG-0201-503",
      "status": 503,
      "title": "The 'com.adobe.experience.platform.ode' service is temporarily unable to serve this request. Please try again later."
    }
  ],
  "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
        }
      }
    }
  ]
}
Copied to your clipboard
{
  "requestId": "72eaa048-207e-4dde-bf16-0cb2b21336d5",
  "handle": [
  ],
  "errors": [
    {
      "type": "https://ns.adobe.com/aep/errors/EXEG-0201-503",
      "status": 503,
      "title": "The 'com.adobe.experience.platform.ode' service is temporarily unable to serve this request. Please try again later."
    }
  ],
  "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
        }
      }
    }
  ]
}

Handling `4xx` and `5xx` responses

Error code	Description
`4xx Bad Request`	Most `4xx` errors, like 400, 403, 404, should not be retried on behalf of the client, except for `429`. These are client errors and will not succeed. The client must address the error before retrying the request.
`429 Too Many Requests`	`429` HTTP response code indicates that the Adobe Experience Platform Edge Network or an upstream service is rate limiting the requests. In this case, the In such a scenario the caller must respect the `Retry-After` response header. Any responses flowing back must carry the HTTP response code with a domain specific error code.
`500 Internal Server Error`	`500` errors are generic, catch-all errors. `500` errors must not be retried, except for `502` and `503`. Intermediaries must respond with a `500` error and may respond with a generic error code/message, or a more domain-specific error code/message.
`502 Bad Gateway`	Indicates that the Adobe Experience Platform Edge Network received an invalid response from upstream servers. This can happen due to network issues between servers. The temporary network issue may resolve and thus a retry may resolve the issue, so recipients of `502` errors may retry the request after some time.
`503 Service Unavailable`	This error code indicates that the service is temporarily unavailable. This can happen during maintenance periods. Recipients of `503` errors may retry the request, but must respect the `Retry-After` header.
`504 Gateway Timeout`	Indicates that Adobe Experience Platform Edge Network request to the upstream servers has timed-out. This can happen due to network issues between servers, DNS issues, or other network issues. The temporary network issues may be resolved after some time and a retry may solve the issue.