> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myunite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> API error format, every code and how to resolve each one.

When a call fails, the response carries the HTTP status and a JSON body:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the pretests:write scope.",
    "requestId": "req_0123456789abcdef0123456789abcdef",
    "docUrl": "https://docs.myunite.ai/errors#insufficient_scope",
    "param": "scope"
  }
}
```

* `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.

```bash curl theme={null}
curl -i https://myunite.ai/api/v1/quota \
  -H "Authorization: Bearer unite_live_YOUR_KEY_HERE"
```

```javascript JavaScript theme={null}
const res = await fetch("https://myunite.ai/api/v1/quota", {
  headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  console.error(error.code, error.requestId);
  if (error.code === "rate_limited") {
    const wait = Number(res.headers.get("Retry-After") ?? "1");
    // wait `wait` seconds and try again
  }
}
```

```python Python theme={null}
import os
import requests

res = requests.get(
    "https://myunite.ai/api/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
)
if not res.ok:
    error = res.json()["error"]
    print(error["code"], error["requestId"])
    if error["code"] == "rate_limited":
        wait = int(res.headers.get("Retry-After", "1"))
        # wait `wait` seconds and try again
```

## 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](https://docs.myunite.ai/en/authentication.md).

### `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](https://docs.myunite.ai/en/rate-limits.md).

### `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](https://docs.myunite.ai/en/idempotency.md).

### `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](https://docs.myunite.ai/en/uploads.md).

### `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](https://docs.myunite.ai/en/pretests/digital.md).

### `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](https://docs.myunite.ai/en/results.md).

### `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](https://docs.myunite.ai/en/webhooks.md).

### `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](https://docs.myunite.ai/en/webhooks.md).

### `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](https://docs.myunite.ai/en/idempotency.md)). If it persists, contact support and share the `requestId` from the response (the same value as `X-Request-Id`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.