Skip to main content
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

CodeHTTP statusMeaningAction
VALIDATION_ERROR400Request body failed schema validationFix the payload per the details array
INVALID_REQUEST400 / 409Request isn’t valid for the resource’s state (for example, an upload that already completed)Check the request against the current resource state
UNAUTHORIZED401Missing or invalid API keyCheck the Authorization header and key validity
FORBIDDEN403API key lacks permission for this resourceContact Adclear to adjust key scoping
NOT_FOUND404Resource does not existVerify the resource ID. It may have been deleted
CONFLICT409Resource not in the expected state (uploads not ready, version not editable)Retry with back-off
PAYLOAD_TOO_LARGE413File exceeds the size limit for its formatCheck the format limits in Introduction
RATE_LIMITED429Too many requestsHonour the Retry-After header
INTERNAL_ERROR500Unexpected server errorRetry once. If it persists, contact support
UPSTREAM_ERROR502A dependency failed transientlyRetry after a short delay

​
Rate limits

ServiceScopeLimit
Adclear APIAll /v1/* endpoints60 requests/minute per API key
File APIPOST /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

  • 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.
  • Check the key hasn’t been revoked.
The API key authenticates but isn’t fully configured for your organisation. Contact Adclear support with the correlationId from the error response.
Honour the Retry-After header. If you’re regularly hitting the limit, batch requests or contact support to discuss your usage.
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.