Ir para o conteúdo

Guias

Erros

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

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"]
}
CampoSignificado
typea URL da seção desta página que descreve o erro
titleum título curto, em francês
statuso status HTTP
codeo identificador estável do erro: teste este
detailuma explicação legível, em francês, que pode mudar entre versões
request_ido 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.

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.

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.

Uma dúvida sobre a API, ou um erro nesta página? Escreva para nós.