# Erros

> O formato dos erros e o que fazer para cada código.

Source: https://piqline.com/pt/docs/api/errors

Todo erro da API é uma resposta `application/problem+json`, no formato RFC 9457:

```json
{
  "type": "https://piqline.com/docs/api/errors#insufficient_scope",
  "title": "Scope insuffisant",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "searchWeb demande le scope explore.",
  "request_id": "8c0c051b-c3e6-4fa0-8b98-0aa227cf3c2a",
  "missing_scopes": ["explore"]
}
```

| Campo | Significado |
| --- | --- |
| `type` | a URL da seção desta página que descreve o erro |
| `title` | um título curto, em francês |
| `status` | o status HTTP |
| `code` | o identificador estável do erro: teste este |
| `detail` | uma explicação legível, em francês, que pode mudar entre versões |
| `request_id` | o ID da requisição, também presente no cabeçalho `X-Request-Id` |

Dependendo do erro, outros campos são adicionados: `missing_scopes`, `issues`.

Ao nos escrever, cite o `request_id`. Ele localiza a requisição nos nossos logs e, se a chave era válida, no histórico de Configurações → API e MCP. O formulário está na [página de contato](/contact).

## Códigos

### `missing_key`

**401** · Chave de API ausente

**Causa.** A requisição não traz nenhuma chave.

**O que fazer.** Envie `Authorization: Bearer piq_live_…` (ou `x-api-key`).

### `invalid_key`

**401** · Chave de API inválida

**Causa.** A chave está malformada (cópia truncada ou redigitada), é desconhecida, foi revogada ou expirou, ou o criador saiu do workspace. `detail` distingue um problema de formato de um problema de status.

**O que fazer.** Confira a cópia. Se a chave foi revogada ou expirou, crie uma nova em Configurações → API e MCP.

### `insufficient_scope`

**403** · Scope insuficiente

**Causa.** A chave não tem um scope que a rota ou a ferramenta exige. `missing_scopes` os lista.

**O que fazer.** Crie uma chave com esses scopes. Uma chave existente mantém seus scopes: eles não podem ser alterados.

### `forbidden`

**403** · Proibido

**Causa.** O papel do criador da chave não dá acesso a esta ferramenta ou agente.

**O que fazer.** Crie a chave a partir de uma conta que tenha o papel exigido (owner ou admin para as ferramentas de escrita e de ação, e para o agente onboarding).

### `not_found`

**404** · Não encontrado

**Causa.** Rota, ferramenta ou agente desconhecido. Os cartões interativos do chat (`askUser`, `proposeSources`, `proposeBoard`…) não são ferramentas chamáveis.

**O que fazer.** Liste os nomes válidos com `GET /api/v1/tools` e `GET /api/v1/agents`.

### `invalid_input`

**422** · Entrada inválida

**Causa.** O corpo não é um JSON válido, ou a entrada não corresponde ao esquema da ferramenta. `issues` aponta cada campo com problema (`path`, `message`).

**O que fazer.** Compare o seu corpo com o `input_schema` da ferramenta (`GET /api/v1/tools/{nom}`).

### `tool_error`

**422** · Erro da ferramenta

**Causa.** A ferramenta recusou a requisição por um motivo ligado aos seus dados, por exemplo um item que não existe neste workspace. `detail` indica o motivo.

**O que fazer.** Corrija a entrada conforme `detail`. A mesma chamada dá a mesma resposta enquanto nada mudar.

### `rate_limited`

**429** · Requisições demais

**Causa.** A chave ultrapassou o limite por minuto.

**O que fazer.** Aguarde o número de segundos indicado no cabeçalho `Retry-After` e tente de novo. Espace as suas chamadas.

### `quota_exceeded`

**429** · Cota diária atingida

**Causa.** A chave atingiu o teto diário de requisições. O contador é zerado todos os dias à meia-noite UTC.

**O que fazer.** Tente de novo depois da meia-noite UTC. Para aumentar o teto, escreva para nós pela [página de contato](/contact).

### `budget_exhausted`

**402** · Créditos mensais esgotados

**Causa.** O workspace da chave atingiu o limite mensal de créditos. Tudo o que gasta (agentes, ferramentas pagas, coleta) é recusado antes da chamada, e um turno de agente em andamento para ao atingir o limite. `detail` indica a data de retomada.

**O que fazer.** Aguarde a data de retomada indicada em `detail`, ou peça a um owner do workspace que aumente o limite.

### `plan_restricted`

**403** · Não incluído no plano

**Causa.** O plano do workspace da chave não permite esta requisição: ele não abre a API, ou a abre somente para leitura e a requisição escreve, assina, ou inicia uma investigação ou um agente. `plan` indica o plano e `api_access` o acesso (`none`, `read`).

**O que fazer.** Peça ao Piqline um plano que abra o acesso de que você precisa: Équipe para leitura, Business para acesso completo.

### `unavailable`

**503** · Serviço indisponível

**Causa.** Um serviço de que a requisição depende não responde: verificação da chave, modelo do agente ou provedor.

**O que fazer.** Tente de novo com um intervalo crescente. Se o erro persistir, cite `request_id` ao nos escrever.

### `not_configured`

**503** · Não configurado

**Causa.** A API não está configurada no servidor: falta uma variável de ambiente.

**O que fazer.** Cite `request_id` ao nos escrever: só o Piqline pode resolver este caso.

### `internal`

**500** · Erro interno

**Causa.** Erro inesperado no lado do Piqline. `detail` permanece vago de propósito.

**O que fazer.** Tente de novo. Se o erro persistir, cite `request_id` ao nos escrever.
