Errors

This guide explains how the Adlocaite API reports errors, which status codes and error codes exist, and how to handle them in your integration.

You can tell if your request was successful by checking the HTTP status code of the response. If a request fails, the response body contains a human-readable error message and, for business errors, a machine-readable error_code you can branch on programmatically.

If you keep running into an error you cannot resolve, contact support@adlocaite.com with the full request, response body, and timestamp -- this speeds up debugging considerably.

Status codes

The API uses standard HTTP status codes:

Name
2xx
Description
The request was successful.
Name
400
Description
Bad request -- invalid or missing request parameters, or an unknown error code.
Name
401
Description
Unauthorized -- the Authorization header is missing or the API key is invalid.
Name
403
Description
Forbidden -- the API key is valid but does not have permission for this resource.
Name
404
Description
Not found -- the screen, offer, deal, or account does not exist, the offer has expired, or no matching advertisements were found.
Name
405
Description
Method not allowed -- the endpoint does not support this HTTP method.
Name
422
Description
Unprocessable -- the request is valid but cannot be fulfilled, for example because no bids meet the minimum price or the account balance is insufficient.
Name
5xx
Description
Server error on our side -- retry with exponential backoff and contact support if the error persists.

Error response formats

The API returns two kinds of error responses.

Validation and authentication errors (status 400, 401, 405) contain a single error field with a human-readable message.

Business errors (for example an unknown screen or an expired offer) additionally contain a machine-readable error_code. Use error_code for programmatic handling and error for logging and debugging -- the message wording may change, the code will not.

Internal server errors (status 500) may include a details field with additional context.

Validation error (401)

{
  "error": "Missing or invalid authorization header. Use: Bearer <publisher_api_key>"
}

Business error (404)

{
  "error": "Screen not found or access denied",
  "error_code": "SCREEN_NOT_FOUND"
}

Error codes

These are the error_code values the API can return, together with the status code they map to:

Name
INVALID_API_KEY
Type
401
Description
The provided API key does not exist or has been revoked.
Name
SCREEN_NOT_FOUND
Type
404
Description
The screen ID (UUID or external ID) is unknown or does not belong to your publisher account.
Name
OFFER_NOT_FOUND
Type
404
Description
The offer ID does not exist.
Name
OFFER_EXPIRED
Type
404
Description
The offer exists but its acceptance window has passed. Request a new offer.
Name
DEAL_NOT_FOUND
Type
404
Description
The referenced deal does not exist.
Name
AD_NOT_FOUND
Type
404
Description
The referenced advertisement does not exist.
Name
ACCOUNT_NOT_FOUND
Type
404
Description
No account is associated with this request.
Name
NO_MATCHES
Type
404
Description
No suitable advertisements were found for this screen at this time. This is an expected outcome, not a fault -- simply request again later. Some responses use the equivalent code NO_MATCHES_FOUND.
Name
PERMISSION_DENIED
Type
403
Description
Your API key is not allowed to access this resource.
Name
NO_SUFFICIENT_BIDS
Type
422
Description
Advertisements matched, but no bid meets the screen's minimum price.
Name
INSUFFICIENT_BALANCE
Type
422
Description
The advertiser's account balance is not sufficient to book the deal.
Name
MISSING_PRICE
Type
400
Description
accepted_price_cents is required when accepting an offer.
Name
INVALID_ACTION
Type
400
Description
The offer response action must be "accept" or "reject".
Name
NO_ASSET_URL
Type
500
Description
A matched advertisement is missing its asset URL. This is a data problem on our side -- contact support.
Name
INTERNAL_ERROR
Type
500
Description
An unexpected error occurred on our side. Retry with backoff; contact support if it persists.

Treat unknown error_code values as non-retryable client errors (the API returns status 400 for them) and log them for review. New codes may be added over time.