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:
{
"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.
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.