Introduction

When working with the API you may encounter errors caused by implementation flaws, wrong input, or environmental differences. Criteo strives to reasonably ensure maximum possible stability of the API system, however in exceptionally rare cases internal server errors may occur. This document will help you to navigate through various types of error messages, the error message structure, and advise you on the common recovery mechanisms for the Criteo API.

Criteo API error types

This section gives a high-level description of various error categories that can be generated from your interaction with the API to help you design error handling mechanism of your application. The following sections will explain in more detail how to handle each error type.

Authorization & Authentication errors

These types of errors may appear if you either don't possess a valid token or the token is lacking access permissions for the endpoint you are trying to reach. This error will also appear if the token has expired. For example, if an account administrator has revoked access for your application you will get HTTP error 403 - Forbidden. A list of common HTTP errors and the recovery strategy can be found in the next section.

Validation errors

Validation errors are commonly caused by user-initiated requests and can be further classified into the following categories:

• User input validation. Typically is evoked when the input supplied by the user is not valid. In this case your application should provide a specific error message to your user based on the error title and error detail. If the error detail is missing, the error title should contain sufficient description.
• Business logic validation. This type of error is evoked when the current action is not possible due to the account configuration state. For example, launching an Ad Set without a positive balance is not possible. In the case of business validation failure, the right strategy would be to request an action from the end user of your application.
• Technical validation. These validation errors are similar to the business logic validation errors, but are caused for technical reasons. For example, error code campaign--ad-set-start-check--cannot-activate-archived-ad-set should cause your application to mark requested Ad Set as archived in your local DB.
  For business-critical operations (e.g start/stop Ad Set) you may want to add the failed operation to a queue for the end user to review.

Dependency failure

Internal error due to temporary unavailability of internal dependency or data persistence failure. This error will have a detailed description of the error in the response body.

Internal server error

Generic server-side errors that are not part of business validation. This could be a temporary network failure or host unavailability. If your application has a UI you should immediately indicate an error in your UI so that the end user can attempt to retry the operation. Alternatively, you can retry automatically within set limit of maximum number of attempts using an exponential back-off strategy (see the next section).

HTTP error codes

The initial information about the success/failure of a request is based on the conformance to the standard HTTP Status Codes. These status codes indicate at a broader level the kind of problem encountered client-side or server-side. The same HTTP status codes are sometimes not sufficient to convey enough information about an error to be helpful.

In order to allow your application be more robust and user-friendly, Criteo provides pertinent information in the response body following RFC-7807 standard. This ensures consistency and predictability of integration by providing additional information about a problem encountered.

Fine-grained failure response

As already mentioned earlier, the Criteo API error-handling mechanism is based on HTTP protocol to report the errors.  The errors section of the HTTP response is an array of errors providing finer details in conjunction with the error response code. An example where this would be a useful error information, is if you are requesting a Statistics report with the start date later than the end date (see the example below). If there are no errors, this section may be omitted.

Error structure

 In order to report domain-specific and validation errors  Criteo API responds with JSON-like object with the error details. Following is an example of such type of response:

{
    "errors": [
        {
            "traceId": "00000000-0000-0000-befd-7e28ff5a4d71",
            "type": "validation",
            "code": "start-after-end-date",
            "instance": "/report",
            "title": "The start date can not be after the end date."
        }
    ]
}

traceId: Technical identifier that allows Criteo engineering team to find correlation between your request and the error in the backend. Include traceId into the report when submitting a support request to us. Mandatory parameter.
type:  Machine-readable field that specifies error category. Use this value to properly inform your user about the outcome and apply the best recovery tactic.  The list of possible values is given below.
instance:  Machine-readable reference to the endpoint to help to identify the specific occurrence of the problem.
code: Machine-readable error code unique to each endpoint.
title: A human-readable description of the error. If your application has UI this can be displayed in dialog title: Mandatory parameter.
detail: A human-readable explanation of the problem. If your application has UI this can be displayed in dialog content.

Warnings structure

Semantically Criteo-API issued warnings are similar to compiler warnings. They indicate that problems may occur in the future. Structurally it is represented as an array returned in HTTP response, similar to error structure.

🚧

Note

• Bulk requests will always return HTTP response 200. If the request fails, partially failed entities will be returned in the array of errors.
• If non-existing Ad Set is requested the error code 403 "insufficient-permissions" will be returned for a single entity endpoint. HTTP status code will be set as 200 for the bulk endpoints.
  For example, GET request to non-existing Ad Set via ad-sets/ endpoint will return 403 response because ad-sets/ is a single entity endpoint.

At the same time, POST to ad-sets/search endpoint in case of insufficient permissions will return successful response with the following body:
{
"data":[]
"warnings":[]
"errors":[]
}
because ad-sets/search is a bulk endpoint.

• Warnings may be returned even for a successful response.

Error category types

Authentication Error codes

authorization-token-missing
The authorization header is missing. Please make sure the authorization header with a valid token is attached to the request.

authorization-token-expired

The authorization token is expired. The token lifetime is 900 seconds from the moment of its generation. If a token is used after the expiration date the error will be thrown. If you would like to avoid manual token management consider installing Criteo transition SDKs: the SDKs offer the token auto-refresh feature. Before a call to the endpoint the library checks that the token is not expired and fetches a new one otherwise.

authorization-token-invalid

The authorization header is invalid: either the wrong format or wrong content of the authorization header was supplied.

authorization-issuer-invalid

The authorization issuer is invalid. The token originator could not be verified. If you receive this error please contact API support.

authorization-unknown

Unknown Authorization error. Please contact API support. If you receive this error please contact API support.

Other Error codes

More error code information can be found on the pages dedicated to the corresponding endpoints.