Errors & rate limits

Every error from both services follows one envelope, so you can handle failures the same way everywhere.

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "type": "field_error", "field": "uploadIds", "message": "Required" }
    ]
  },
  "correlationId": "uuid-for-support"
}

The details array is present on some errors and identifies what to fix. Its entries take one of these shapes: field_error (a bad field), constraint_violation (a limit exceeded), retry_info (when to retry), or upload_not_ready (an upload still processing).

Error codes

Code	HTTP status	Meaning	Action
`VALIDATION_ERROR`	400	Request body failed schema validation	Fix the payload per the `details` array
`INVALID_REQUEST`	400 / 409	Request isn’t valid for the resource’s state (for example, an upload that already completed)	Check the request against the current resource state
`UNAUTHORIZED`	401	Missing, invalid, revoked, or expired API key	Check the `Authorization` header. The `Code:` at the end of the message says why the key was refused
`FORBIDDEN`	403	API key lacks permission for this resource	Contact Adclear to adjust key scoping
`NOT_FOUND`	404	Resource does not exist	Verify the resource ID. It may have been deleted
`CONFLICT`	409	Resource not in the expected state (uploads not ready, version not editable)	Retry with back-off
`PAYLOAD_TOO_LARGE`	413	File exceeds the size limit for its format	Check the format limits in Introduction
`RATE_LIMITED`	429	Too many requests	Honour the `Retry-After` header
`INTERNAL_ERROR`	500	Unexpected server error	Retry once. If it persists, contact support
`UPSTREAM_ERROR`	502 / 503	A dependency failed transiently, or is temporarily unavailable	Retry after a short delay

Rate limits

Service	Scope	Limit
Adclear API	All `/v1/*` endpoints	60 requests/minute per API key
File API	`POST /v1/uploads` (initiation only)	30 requests/minute per API key

Chunk uploads (PUT /v1/uploads/{id}) and status checks (GET /v1/uploads/{id}) are not rate-limited. When you are rate-limited, the response includes a Retry-After header telling you how many seconds to wait. The Adclear API’s 60/minute budget is shared across every /v1/* endpoint, so frequent polling of evaluation status competes with your create and evaluate calls. Prefer webhooks to receive results without spending the budget.

Common issues

401 Unauthorized on every request

Verify the Authorization header is Bearer <key> (note the space after Bearer).
Confirm you’re using the correct key for the environment. Staging and production keys are not interchangeable.
A message ending in Code: KEY_DISABLED means the key was revoked. A message ending in Code: KEY_EXPIRED means it expired (see Key expiry). Generate a new key in Settings > Organisation > API keys.

403 Forbidden

The API key authenticates but isn’t fully configured for your organisation.
If the message is API key is not configured for public API access and you generated the key in Settings, check that the person who generated it is still a member of your organisation and doesn’t hold an external role (external uploader or reviewer). If they have left or changed role, generate a new key from another account (see Keys tied to their creator).
Otherwise, contact Adclear support with the correlationId from the error response.

429 Rate limited

Honour the Retry-After header. If you’re regularly hitting the limit, batch requests or contact support to discuss your usage.

502 from the Adclear API

A transient upstream issue. Retry after 2 to 5 seconds. If it persists, contact support with the correlationId.

General tips

Pass your own trace ID in the X-Correlation-ID request header. Adclear echoes it back in every response.
Always include the correlationId in support requests. It lets us trace the full request lifecycle.
Test against staging before production.
Cache reference data (products, channels, jurisdictions, target markets) and refresh daily.

Get started

Fundamentals

Adclear API

File API

Error envelope

Error codes

Rate limits

Common issues

General tips

​Error envelope

​Error codes

​Rate limits

​Common issues

​General tips

Error envelope

Error codes

Rate limits

Common issues

General tips