Skip to content

Error Handling and Debugging

Catch and respond to errors, set headers for debugging, check response codes, and more.

Throttled Requests and Exponential Backoff

Cardlytics imposes no general rules imposes around throttling incoming requests. Publishers are nevertheless asked to properly handle 429 Too Many Requests response codes by implementing a retry mechanism with exponential back-off if possible. Specific APIs will speak to their SLAs and capacity capabilities.

See this AWS Architecture blog post for more information about exponential backoff.

Request IDs for Traceability

All APIs accept a X-CDLX-Request-ID header which can be used for tracing and debugging requests.

Example

The following example shows how to set the X-CDLX-Request-ID header.

1
2
3
4
% curl -X POST \
  -H 'X-CDLX-Request-Id: 56d5d70e-7fb8-43d3-8331-19bb6930bbdb' \
  -H 'X-CDLX-Session-Token: ${token}' \
  publisher-uk-fiuat.cardlytics.com/v2/ads/getAds

Every endpoint will return the requestId for debugging, corresponding to the value of the X-CDLX-Request-Id header set in the request. If no header was present, a random UUID will be set by the API.

HTTP Response Codes

Cardlytics API endpoints and webhooks all try to adhere to and honor standard HTTP status codes. Below are the response codes that Publishers may see when calling Cardlytics's endpoints and webhooks.

Cardlytics's API endpoints and webhooks adhere to standard HTTP status codes.

Below are the response codes that you may see when calling Cardlytics endpoints and webhooks.

HTTP Response Code Description
200 OK Success. The request is understood and acknowledged. The body of the response may indicate additional context or error conditions.
301 Moved Permanently
302 Found		 Cardlytics does not currently require clients to handle redirects. For future proofing, following 1 redirect for a request to Cardlytics is recommended
401 Unauthorized Request does not include required credentials
403 Forbidden Caller is not allowed to invoke the endpoint
404 Not Found Cardlytics cannot locate the resource requested
405 Method Not Allowed Cardlytics does not support the HTTP method requested. Note that most Cardlytics endpoints support POST only
415 Unsupported Media Type Cardlytics does not understand the body of the request. Note that most Cardlytics endpoints support application/json only
429 Too Many Requests Cardlytics is throttling requests from your client. Note that Cardlytics tries to never respond with this response code but may under extreme circumstances
500 Internal Server Error An unknown or not-handled error
501 Not Implemented Endpoint does not understand the request passed
503 Service Unavailable The specific service is down for maintenance or other reasons

Error Responses

Some 5xx and 4xx responses will be returned with some additional properties to aid in debugging and, in some cases, allow for programmatic error handling.

Error Response Format

Property Description
type The distinct Error Type which took place
title A brief title for the exception
status Numerical HTTP response code
validationErrors Validation errors which occurred, if any

Error Types

Name Code Description
HttpMessageNotReadable 400 Request could not be parsed
ValidationException 400 Request contains missing or invalid parameters
SessionValidationException 500 Session could not be validated
InternalServerError 500 Generic internal server error

Examples

ValidationException Example

1
2
3
4
5
6
7
8
9
{
    "type": "ValidationException",
    "title": "Bad request",
    "status": 400,
    "validationErrors": [
        "channel: Channel cannot be null."
    ],
    "requestId": "d35ff5ea-a80e-4c93-92df-9b6ae7a12773"
}

SessionValidationException Example

1
2
3
4
5
6
{
    "type": "SessionValidationException",
    "title": "Session expired or invalid",
    "status": 401,
    "requestId": "d35ff5ea-a80e-4c93-92df-9b6ae7a12773"
}

InternalServerError Example

1
2
3
4
5
6
{
    "type": "InternalServerError",
    "title": "Internal Server Error",
    "status": 500,
    "requestId": "d35ff5ea-a80e-4c93-92df-9b6ae7a12773"
}