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:
{
"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 | Significato |
|---|---|
type | l'URL della sezione di questa pagina che descrive l'errore |
title | un titolo breve, in francese |
status | lo stato HTTP |
code | l'identificatore stabile dell'errore: testa questo |
detail | una spiegazione leggibile, in francese, che può cambiare tra le versioni |
request_id | l'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.