Skip to main content
When a call fails, the response carries the HTTP status and a JSON body:
  • code: stable identifier. Build your logic on it, never on the message.
  • message: explanation in English. The text may change.
  • requestId: the same as the X-Request-Id header. Share it when you contact support.
  • docUrl: link to the section of this page.
  • param: the field, parameter or header the error refers to. Only present when there is one.

Codes

invalid_api_key

Status: 401 What happened: The key was not sent, is malformed or does not exist. How to fix it: Send Authorization: Bearer <key>. Check that you copied the whole key, without spaces, and that it is a production key. If you lost the key, create another one in the dashboard.

api_key_revoked

Status: 401 What happened: The key was revoked by an administrator. How to fix it: Create a new key in the dashboard and update your integration.

api_key_expired

Status: 401 What happened: The key passed the expiry chosen when it was created. How to fix it: Create a new key and update your integration. Prefer replacing keys before they expire.

insufficient_scope

Status: 403 What happened: The key does not have the permission the route requires. The param field carries scope. How to fix it: Reading requires pretests:read. Uploads and creation require pretests:write. Webhook endpoints require webhooks:manage. Create a key with the needed permission. See Authentication.

feature_not_enabled

Status: 403 What happened: The API is not enabled for this workspace. How to fix it: Contact the Unite team to enable access.

key_owner_not_member

Status: 403 What happened: The person who created the key left the workspace or lost access to it. How to fix it: Ask an administrator to create a new key, with an account that has access to the workspace. The old key does not work again.

rate_limited

Status: 429 What happened: The key exceeded the per-minute limit (600 reads or 60 writes). How to fix it: Wait the seconds given in the Retry-After header and try again. See Rate limits.

concurrency_limit

Status: 429 What happened: The workspace already has too many API-created pre-tests in progress (about 10). How to fix it: Wait for Retry-After (30 seconds) or for a pre-test to finish, and try again with the same Idempotency-Key.

invalid_request

Status: 400 or 422 What happened: A field, parameter or header is invalid. It comes back as 400 (body that is not JSON, Idempotency-Key in the wrong format) or 422 (field with an invalid value, unknown field, query parameter not allowed). The param field says which one. How to fix it: Fix the field given in param and send again. The error does not consume quota.

idempotency_key_required

Status: 400 What happened: The Idempotency-Key header was not sent when creating the pre-test. How to fix it: Send a value of 1 to 255 visible ASCII characters. See Idempotency.

idempotency_conflict

Status: 409 What happened: The same Idempotency-Key was already used with a different body. How to fix it: To repeat the call, send exactly the same body. To create another pre-test, use a new key.

idempotency_key_retired

Status: 409 What happened: The Idempotency-Key belongs to a pre-test that was deleted and cannot be reused. How to fix it: Use a new Idempotency-Key.

upload_not_found

Status: 404 What happened: The uploadId does not exist in this workspace: the file was not uploaded, the id is wrong or it belongs to another workspace. How to fix it: Request an address with POST /uploads, upload the file and use the returned uploadId. See File uploads.

upload_invalid

Status: 422 What happened: The file type is not accepted, the content does not match the declared type, the video has no readable duration or the email channel received a video. How to fix it: Use png, jpeg, webp, gif, mp4 or mov. For email, upload an image. Upload again with an intact file.

file_too_large

Status: 422 What happened: The file exceeds the limit: 25 MB for images and 200 MB for videos. How to fix it: Reduce the file and upload again.

video_too_long

Status: 422 What happened: The video is longer than 30 seconds. How to fix it: Trim the video to 30 seconds or less and upload again. Quota is not consumed.

invalid_ooh_format

Status: 422 What happened: The ooh.format value does not exist in the catalog. How to fix it: Use the key of a format from GET /catalog, under ooh.formats.

invalid_placement

Status: 422 What happened: The placement (digital.placement) does not exist on the chosen platform. For example, stories on TikTok. How to fix it: Use a valid placement for the platform. See Digital pre-test.

brand_not_found

Status: 404 What happened: The brandId does not exist in this workspace. How to fix it: Use a brand id from GET /catalog, under brands, or omit the field.

quota_exhausted

Status: 402 What happened: The workspace pre-test quota is used up. How to fix it: Check GET /quota. When the balance is restored, repeat the same Idempotency-Key: creation is attempted again and may use one quota unit.

not_found

Status: 404 What happened: The pre-test or the webhook endpoint does not exist in this workspace. How to fix it: Check the id. Ids from another workspace also respond 404.

report_not_ready

Status: 409 What happened: The PDF only exists after the pre-test reaches completed. How to fix it: Poll the pre-test until the status is completed and request the PDF again. See Results.

webhook_url_rejected

Status: 422 What happened: The endpoint address is not accepted. The param field carries url. The reasons are: it does not use https, it uses a port other than 443, it includes a username and password, it does not resolve on the internet or it points to a private or local address. How to fix it: Use an https address on the default port, without username and password, that resolves to a public server. See Webhooks.

webhook_endpoint_limit

Status: 422 What happened: The workspace already has 5 webhook endpoints, counting disabled ones. How to fix it: Delete an endpoint with DELETE /webhook-endpoints/{id} and create the new one. See Webhooks.

internal_error

Status: 500 What happened: Something failed on our side. How to fix it: Try again after a few moments. On POST /pretests, repeat with the same Idempotency-Key: the creation may have happened despite the failure, and a new key may create, and charge for, a second pre-test (see Idempotency). If it persists, contact support and share the requestId from the response (the same value as X-Request-Id).