Guides
Erreurs
Le format des erreurs et quoi faire pour chaque code.
Toute erreur de l’API est une réponse application/problem+json, au format 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"]
}| Champ | Sens |
|---|---|
type | l’adresse de la section de cette page qui décrit l’erreur |
title | un titre court, en français |
status | le statut HTTP |
code | l’identifiant stable de l’erreur : testez celui-ci |
detail | une explication lisible, qui peut changer d’une version à l’autre |
request_id | l’identifiant de la requête, aussi dans l’en-tête X-Request-Id |
Selon l’erreur, d’autres champs s’ajoutent : missing_scopes, issues.
Quand vous nous écrivez, citez le request_id. Il retrouve la requête dans nos journaux, et dans l’historique de Settings → API and MCP si la clé était valide. Le formulaire se trouve sur la page contact.
Codes#
missing_key#
401 · Clé API absente
Cause. La requête ne porte aucune clé.
À faire. Envoyez Authorization: Bearer piq_live_… (ou x-api-key).
invalid_key#
401 · Clé API invalide
Cause. La clé est mal formée (copie tronquée ou retapée), inconnue, révoquée ou expirée, ou son créateur a quitté le workspace. detail distingue un défaut de format d’un défaut de statut.
À faire. Vérifiez la copie. Si la clé est révoquée ou expirée, créez-en une dans Settings → API and MCP.
insufficient_scope#
403 · Scope insuffisant
Cause. La clé n’a pas un scope exigé par la route ou l’outil. missing_scopes les liste.
À faire. Créez une clé avec ces scopes. Une clé existante garde ses scopes : on ne les modifie pas.
forbidden#
403 · Accès refusé
Cause. Le rôle du créateur de la clé ne donne pas accès à cet outil ou à cet agent.
À faire. Créez la clé depuis un compte qui a le rôle requis (owner ou admin pour les outils d’écriture, d’action et pour l’agent onboarding).
not_found#
404 · Introuvable
Cause. Route, outil ou agent inconnu. Les cartes interactives du chat (askUser, proposeSources, proposeBoard…) ne sont pas des outils appelables.
À faire. Listez les noms valides avec GET/api/v1/tools et GET/api/v1/agents.
invalid_input#
422 · Entrée invalide
Cause. Le corps n’est pas du JSON valide, ou l’entrée ne respecte pas le schéma de l’outil. issues indique chaque champ fautif (path, message).
À faire. Comparez votre corps avec input_schema de l’outil (GET/api/v1/tools/{nom}).
tool_error#
422 · L'outil a refusé la requête
Cause. L’outil a refusé la requête pour une raison propre à vos données, par exemple un item introuvable dans ce workspace. detail donne la raison.
À faire. Corrigez l’entrée selon detail. Le même appel donnera la même réponse tant que rien ne change.
rate_limited#
429 · Trop de requêtes
Cause. La clé a dépassé sa limite par minute.
À faire. Attendez le nombre de secondes de l’en-tête Retry-After, puis relancez. Espacez vos appels.
quota_exceeded#
429 · Quota journalier atteint
Cause. La clé a atteint son plafond de requêtes du jour. Le compteur repart à zéro chaque jour à minuit UTC.
À faire. Réessayez après minuit UTC. Pour relever le plafond, écrivez-nous par la page contact.
unavailable#
503 · Service indisponible
Cause. Un service dont dépend la requête ne répond pas : vérification de la clé, modèle de l’agent ou fournisseur.
À faire. Réessayez avec un délai croissant. Si l’erreur dure, citez request_id en nous écrivant.
not_configured#
503 · API non configurée sur ce serveur
Cause. L’API n’est pas configurée côté serveur : il manque une variable d’environnement.
À faire. Citez request_id en nous écrivant : seul Piqline peut corriger ce cas.
internal#
500 · Erreur interne
Cause. Erreur inattendue côté Piqline. detail reste volontairement vague.
À faire. Réessayez. Si l’erreur persiste, citez request_id en nous écrivant.