code: stable identifier. Build your logic on it, never on the message.message: explanation in English. The text may change.requestId: the same as theX-Request-Idheader. 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).