Error envelope
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
Rate limits
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
403 Forbidden
403 Forbidden
The API key authenticates, but the request isn’t permitted. The message says why:
API key is not configured for public API access: if 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).The acting user is not a current member of this organization: the key’s user, or the act-on-behalf user, has left your organisation.The acting user does not have access to this workspace: give the acting user access to the key’s workspace in Settings > Organisation > Users.The acting user's role does not permit this operation: the acting user’s role can’t submit promotions, so it can’t create or submit versions.The user in X-External-User-Email does not have review permission for country GB(orThe API key's user does not have review permission for country GBon an ordinary key): returned when recording a decision. The acting user has no review permission for the promotion’s country. Pass the email of the person who actually made the decision, or ask an admin to grant that person review permission for the country.
correlationId from the error response.429 Rate limited
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
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-IDrequest header. Adclear echoes it back in every response. - Always include the
correlationIdin 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.