Skip to main content

​
401 Unauthorized

Symptom: Every request returns 401 with error code UNAUTHORIZED. Checklist:
  1. Verify the Authorization header format is Bearer <your-api-key> (note the space after Bearer)
  2. Confirm you are using the correct key for the environment — staging and production keys are not interchangeable (see Environments)
  3. Check the key has not been revoked or expired

​
403 Forbidden

Symptom: Requests authenticate but return 403 with error code FORBIDDEN. Cause: The API key exists but is not fully configured for your organisation. Action: Contact Adclear support. Include the correlationId from the error response.

​
409 Conflict When Creating a Promotion

Symptom: POST /v1/promotions returns 409 with error code CONFLICT and a detail of type upload_not_ready. Cause: One or more files referenced in uploadIds have not finished uploading. Resolution:
  1. For each upload ID, poll GET /v1/uploads/{uploadId} until status is completed
  2. Retry the promotion creation once all uploads are complete
Small files typically complete within seconds. Larger files (100 MB+) may take longer. Use exponential back-off (e.g. 1s, 2s, 4s, up to ~30s).

​
Evaluation Stuck in Processing

Symptom: GET .../evaluation continues to return status: "processing" for longer than expected. Context: Typical evaluation time is 30–90 seconds depending on content size and complexity. Resolution:
  1. Continue polling every 5–10 seconds for up to 5 minutes
  2. If still processing after 5 minutes, re-trigger the evaluation with POST .../evaluate
  3. If the issue persists, contact Adclear support with the correlationId and evaluationId
Configure a webhook to receive results asynchronously instead of polling. This avoids timeout concerns entirely.

​
Webhook Not Being Received

Symptom: Evaluation completes (confirmed via polling) but your webhook endpoint is never called. Checklist:
  1. Confirm your endpoint URL is HTTPS — HTTP endpoints are not supported
  2. Verify your endpoint responds with 2xx within 30 seconds
  3. Check your signature verification logic — if verification fails silently, you may be discarding valid payloads (see Webhook Signature Verification)
  4. Confirm webhooks are configured for your organisation — contact Adclear if unsure
Failed deliveries are retried with exponential back-off. If your endpoint was temporarily down, the webhook may arrive later.

​
429 Rate Limited

Symptom: Requests return 429 with error code RATE_LIMITED. Resolution: Honour the Retry-After header in the response, which indicates how many seconds to wait before retrying. See Rate Limits for specific limits per service.

​
502 Error From the Integration API

Symptom: Occasional 502 responses with error code UPSTREAM_ERROR or INTERNAL_ERROR. Cause: A transient issue with an upstream service. Resolution:
  1. Retry the request after a short delay (2–5 seconds)
  2. If the error persists, contact Adclear support with the correlationId

​
General Tips

Always include the correlationId from error responses when contacting Adclear support. It allows us to trace the full request lifecycle for fast debugging.
  • Use the X-Correlation-ID request header to pass your own trace ID — it will be echoed back in every response and threaded through the system
  • Test your integration against the staging environment before going to production
  • Cache reference data (products, channels, jurisdictions, target markets) and refresh periodically — these change infrequently