# Erreurs

> Le format des erreurs et quoi faire pour chaque code.

Source: https://piqline.com/fr/docs/api/errors

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"]
}
```

| 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](/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](/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.
