Error handling

Last update: 2023-12-06
  • Created for:
  • Developer


API errors in Adobe Experience Platform Edge Network Server 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


Server API errors can also be split by severity:

  • Fatal errors will 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 will be changed to 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. Check out the error types section to see the expected status code, corresponding to each error type.

Errors will be 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<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.
   "title":"Unprocessable entity",
   "detail":"Invalid request (report attached). Please check your input and try again.",
         "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"

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 Server API will change 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 Edge gateway’s standard response, which is of type application/json.

  "requestId": "72eaa048-207e-4dde-bf16-0cb2b21336d5",
  "handle": [
  "errors": [
      "type": "",
      "status": 503,
      "title": "The 'com.adobe.experience.platform.ode' service is temporarily unable to serve this request. Please try again later."
  "warnings": [
      "type": "",
      "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.

On this page