> ## 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.

# Erros

> Formato dos erros da API, todos os códigos e como resolver cada um.

Quando uma chamada falha, a resposta traz o status HTTP e um corpo JSON:

```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`: identificador estável. Programe a sua lógica por ele, nunca pela mensagem.
* `message`: explicação em inglês. O texto pode mudar.
* `requestId`: igual ao cabeçalho `X-Request-Id`. Informe-o ao falar com o suporte.
* `docUrl`: link para a seção desta página.
* `param`: o campo, parâmetro ou cabeçalho a que o erro se refere. Só aparece quando há um.

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

```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");
    // espere `wait` segundos e tente de novo
  }
}
```

```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"))
        # espere `wait` segundos e tente de novo
```

## Códigos

### `invalid_api_key`

**Status:** `401`

**O que aconteceu:** A chave não foi enviada, está mal formatada ou não existe.

**Como resolver:** Envie `Authorization: Bearer <chave>`. Confira se copiou a chave inteira, sem espaços, e se ela é de produção. Se perdeu a chave, crie outra no painel.

### `api_key_revoked`

**Status:** `401`

**O que aconteceu:** A chave foi revogada por um administrador.

**Como resolver:** Crie uma chave nova no painel e atualize sua integração.

### `api_key_expired`

**Status:** `401`

**O que aconteceu:** A chave passou da validade escolhida na criação.

**Como resolver:** Crie uma chave nova e atualize sua integração. Prefira trocar antes de vencer.

### `insufficient_scope`

**Status:** `403`

**O que aconteceu:** A chave não tem a permissão que a rota exige. O campo `param` traz `scope`.

**Como resolver:** Leitura exige `pretests:read`. Upload e criação exigem `pretests:write`. Endpoints de webhook exigem `webhooks:manage`. Crie uma chave com a permissão necessária. Veja [Autenticação](https://docs.myunite.ai/authentication.md).

### `feature_not_enabled`

**Status:** `403`

**O que aconteceu:** A API não está liberada para este workspace.

**Como resolver:** Fale com o time da Unite para liberar o acesso.

### `key_owner_not_member`

**Status:** `403`

**O que aconteceu:** Quem criou a chave saiu do workspace ou perdeu o acesso a ele.

**Como resolver:** Peça a um administrador que crie uma chave nova, com uma conta que tenha acesso ao workspace. A chave antiga não volta a funcionar.

### `rate_limited`

**Status:** `429`

**O que aconteceu:** A chave passou do limite por minuto (600 leituras ou 60 escritas).

**Como resolver:** Espere os segundos do cabeçalho `Retry-After` e tente de novo. Veja [Limites de uso](https://docs.myunite.ai/rate-limits.md).

### `concurrency_limit`

**Status:** `429`

**O que aconteceu:** O workspace já tem pré-testes demais em andamento criados pela API (cerca de 10).

**Como resolver:** Espere `Retry-After` (30 segundos) ou o término de algum pré-teste e tente de novo com a mesma `Idempotency-Key`.

### `invalid_request`

**Status:** `400` ou `422`

**O que aconteceu:** Algum campo, parâmetro ou cabeçalho está inválido. Volta como `400` (corpo que não é JSON, `Idempotency-Key` fora do formato) ou `422` (campo com valor inválido, campo desconhecido, parâmetro de consulta fora do permitido). O campo `param` indica qual.

**Como resolver:** Corrija o campo indicado em `param` e envie de novo. O erro não consome a cota.

### `idempotency_key_required`

**Status:** `400`

**O que aconteceu:** O cabeçalho `Idempotency-Key` não foi enviado na criação do pré-teste.

**Como resolver:** Envie um valor de 1 a 255 caracteres ASCII visíveis. Veja [Idempotência](https://docs.myunite.ai/idempotency.md).

### `idempotency_conflict`

**Status:** `409`

**O que aconteceu:** A mesma `Idempotency-Key` já foi usada com um corpo diferente.

**Como resolver:** Para repetir a chamada, envie exatamente o mesmo corpo. Para criar outro pré-teste, use uma chave nova.

### `idempotency_key_retired`

**Status:** `409`

**O que aconteceu:** A `Idempotency-Key` pertence a um pré-teste que foi excluído e não pode ser reutilizada.

**Como resolver:** Use uma `Idempotency-Key` nova.

### `upload_not_found`

**Status:** `404`

**O que aconteceu:** O `uploadId` não existe neste workspace: o arquivo não foi enviado, o id está errado ou é de outro workspace.

**Como resolver:** Peça um endereço em `POST /uploads`, envie o arquivo e use o `uploadId` devolvido. Veja [Envio de arquivos](https://docs.myunite.ai/uploads.md).

### `upload_invalid`

**Status:** `422`

**O que aconteceu:** O tipo de arquivo não é aceito, o conteúdo não corresponde ao tipo declarado, o vídeo não tem duração legível ou o canal e-mail recebeu um vídeo.

**Como resolver:** Use png, jpeg, webp, gif, mp4 ou mov. Em e-mail, envie uma imagem. Refaça o envio com um arquivo íntegro.

### `file_too_large`

**Status:** `422`

**O que aconteceu:** O arquivo passa do limite: 25 MB para imagem e 200 MB para vídeo.

**Como resolver:** Reduza o arquivo e envie de novo.

### `video_too_long`

**Status:** `422`

**O que aconteceu:** O vídeo tem mais de 30 segundos.

**Como resolver:** Corte o vídeo para até 30 segundos e envie de novo. A cota não é consumida.

### `invalid_ooh_format`

**Status:** `422`

**O que aconteceu:** O valor de `ooh.format` não existe no catálogo.

**Como resolver:** Use o `key` de um formato de `GET /catalog`, em `ooh.formats`.

### `invalid_placement`

**Status:** `422`

**O que aconteceu:** A posição (`digital.placement`) não existe na plataforma escolhida. Por exemplo, `stories` no TikTok.

**Como resolver:** Use uma posição válida da plataforma. Veja [Pré-teste digital](https://docs.myunite.ai/pretests/digital.md).

### `brand_not_found`

**Status:** `404`

**O que aconteceu:** O `brandId` não existe neste workspace.

**Como resolver:** Use um `id` de marca de `GET /catalog`, em `brands`, ou omita o campo.

### `quota_exhausted`

**Status:** `402`

**O que aconteceu:** A cota de pré-testes do workspace acabou.

**Como resolver:** Consulte `GET /quota`. Quando o saldo for restabelecido, repita a mesma `Idempotency-Key`: a criação tenta de novo e pode usar uma unidade da cota.

### `not_found`

**Status:** `404`

**O que aconteceu:** O pré-teste ou o endpoint de webhook não existe neste workspace.

**Como resolver:** Confira o id. Ids de outro workspace também respondem `404`.

### `report_not_ready`

**Status:** `409`

**O que aconteceu:** O PDF só existe depois que o pré-teste chega a `completed`.

**Como resolver:** Consulte o pré-teste até o status ser `completed` e peça o PDF de novo. Veja [Resultados](https://docs.myunite.ai/results.md).

### `webhook_url_rejected`

**Status:** `422`

**O que aconteceu:** O endereço do endpoint não é aceito. O campo `param` traz `url`. Os motivos são: não usa `https`, usa uma porta diferente da 443, traz usuário e senha, não resolve na internet ou aponta para um endereço privado ou local.

**Como resolver:** Use um endereço `https` na porta padrão, sem usuário e senha, que resolva para um servidor público. Veja [Webhooks](https://docs.myunite.ai/webhooks.md).

### `webhook_endpoint_limit`

**Status:** `422`

**O que aconteceu:** O workspace já tem 5 endpoints de webhook, contando os desativados.

**Como resolver:** Apague um endpoint com `DELETE /webhook-endpoints/{id}` e crie o novo. Veja [Webhooks](https://docs.myunite.ai/webhooks.md).

### `internal_error`

**Status:** `500`

**O que aconteceu:** Algo falhou do nosso lado.

**Como resolver:** Tente de novo depois de alguns instantes. Em `POST /pretests`, repita **com a mesma `Idempotency-Key`**: a criação pode ter acontecido mesmo com a falha, e uma chave nova pode criar, e cobrar, um segundo pré-teste (veja [Idempotência](https://docs.myunite.ai/idempotency.md)). Se persistir, fale com o suporte e informe o `requestId` da resposta (o mesmo valor de `X-Request-Id`).


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