Vai al contenuto

Guide

Errori

Il formato degli errori e che cosa fare per ogni codice.

Ogni errore dell'API è una risposta application/problem+json, nel 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"]
}
CampoSignificato
typel'URL della sezione di questa pagina che descrive l'errore
titleun titolo breve, in francese
statuslo stato HTTP
codel'identificatore stabile dell'errore: testa questo
detailuna spiegazione leggibile, in francese, che può cambiare tra le versioni
request_idl'ID della richiesta, presente anche nell'header X-Request-Id

A seconda dell'errore, vengono aggiunti altri campi: missing_scopes, issues.

Quando ci scrivi, indica il request_id. Permette di ritrovare la richiesta nei nostri log e, se la chiave era valida, nella cronologia di Impostazioni → API e MCP. Il modulo è nella pagina dei contatti.

Codici#

missing_key#

401 · Chiave API mancante

Causa. La richiesta non contiene alcuna chiave.

Che cosa fare. Invia Authorization: Bearer piq_live_… (oppure x-api-key).

invalid_key#

401 · Chiave API non valida

Causa. La chiave è malformata (copia troncata o ridigitata), sconosciuta, revocata o scaduta, oppure il suo creatore ha lasciato il workspace. detail distingue un problema di formato da un problema di stato.

Che cosa fare. Controlla la copia. Se la chiave è revocata o scaduta, creane una nuova in Impostazioni → API e MCP.

insufficient_scope#

403 · Scope insufficiente

Causa. Alla chiave manca uno scope richiesto dalla route o dal tool. missing_scopes li elenca.

Che cosa fare. Crea una chiave con quegli scope. Una chiave esistente mantiene i suoi scope: non possono essere modificati.

forbidden#

403 · Accesso negato

Causa. Il ruolo del creatore della chiave non dà accesso a questo tool o a questo agente.

Che cosa fare. Crea la chiave da un account che ha il ruolo richiesto (owner o admin per i tool di scrittura e di azione, e per l'agente onboarding).

not_found#

404 · Non trovato

Causa. Route, tool o agente sconosciuto. Le card interattive della chat (askUser, proposeSources, proposeBoard…) non sono tool richiamabili.

Che cosa fare. Elenca i nomi validi con GET/api/v1/tools e GET/api/v1/agents.

invalid_input#

422 · Input non valido

Causa. Il corpo non è JSON valido, oppure l'input non corrisponde allo schema del tool. issues indica ogni campo errato (path, message).

Che cosa fare. Confronta il tuo corpo con l'input_schema del tool (GET/api/v1/tools/{nom}).

tool_error#

422 · Errore del tool

Causa. Il tool ha rifiutato la richiesta per un motivo legato ai tuoi dati, per esempio un elemento che non esiste in questo workspace. detail indica il motivo.

Che cosa fare. Correggi l'input secondo detail. La stessa chiamata dà la stessa risposta finché nulla cambia.

rate_limited#

429 · Troppe richieste

Causa. La chiave ha superato il limite al minuto.

Che cosa fare. Attendi il numero di secondi indicato nell'header Retry-After, poi riprova. Distanzia le chiamate.

quota_exceeded#

429 · Quota giornaliera raggiunta

Causa. La chiave ha raggiunto il limite giornaliero di richieste. Il contatore si azzera ogni giorno a mezzanotte UTC.

Che cosa fare. Riprova dopo la mezzanotte UTC. Per aumentare il limite, scrivici dalla pagina dei contatti.

budget_exhausted#

402 · Crediti mensili esauriti

Causa. Il workspace della chiave ha raggiunto il limite mensile di crediti. Tutto ciò che consuma (agenti, tool a pagamento, raccolta) viene rifiutato prima della chiamata, e un turno di agente in corso si ferma quando raggiunge il limite. detail indica la data di ripresa.

Che cosa fare. Attendi la data di ripresa indicata in detail, oppure chiedi a un owner del workspace di aumentare il limite.

plan_restricted#

403 · Non incluso nel piano

Causa. Il piano del workspace della chiave non consente questa richiesta: non apre l'API, oppure la apre in sola lettura e la richiesta scrive, si iscrive, o avvia un'indagine o un agente. plan indica il piano e api_access l'accesso (none, read).

Che cosa fare. Chiedi a Piqline un piano che apra l'accesso di cui hai bisogno: Équipe per la lettura, Business per l'accesso completo.

unavailable#

503 · Servizio non disponibile

Causa. Un servizio da cui dipende la richiesta non risponde: verifica della chiave, modello dell'agente o provider.

Che cosa fare. Riprova con un intervallo crescente. Se l'errore persiste, indica request_id quando ci scrivi.

not_configured#

503 · Non configurato

Causa. L'API non è configurata sul server: manca una variabile d'ambiente.

Che cosa fare. Indica request_id quando ci scrivi: solo Piqline può risolvere questo caso.

internal#

500 · Errore interno

Causa. Errore imprevisto lato Piqline. detail resta volutamente vago.

Che cosa fare. Riprova. Se l'errore persiste, indica request_id quando ci scrivi.

Una domanda sull'API, o un errore in questa pagina? Scrivici.