Aller au contenu

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 :

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"]
}
ChampSens
typel’adresse de la section de cette page qui décrit l’erreur
titleun titre court, en français
statusle statut HTTP
codel’identifiant stable de l’erreur : testez celui-ci
detailune explication lisible, qui peut changer d’une version à l’autre
request_idl’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.

budget_exhausted#

402 · Plafond du mois atteint

Cause. Le workspace de la clé a atteint son plafond de crédits du mois. Tout ce qui dépense (agents, outils payants, collecte) est refusé avant l’appel, et un tour d’agent en cours s’arrête quand il l’atteint. detail donne la date de reprise.

À faire. Attendez la date de reprise indiquée dans detail, ou demandez à un owner du workspace de relever le plafond.

plan_restricted#

403 · Hors du palier du workspace

Cause. Le palier du workspace de la clé ne permet pas cette requête : il n’ouvre pas l’API, ou il l’ouvre en lecture seule et la requête écrit, s’abonne ou lance une enquête ou un agent. plan donne le palier et api_access l’accès (none, read).

À faire. Demandez à Piqline un palier qui ouvre l’accès voulu : Équipe pour la lecture, Business pour l’accès complet.

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.

Une question sur l’API, ou une erreur dans cette page ? Écrivez-nous.