# Erreurs et limites de taux

### Format d'erreur

Chaque réponse d'erreur utilise la même forme JSON et un code d'état HTTP approprié :

```json
{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "Missing required scope: govern:checkpoints:write"
}
```

| Champ | Désignation des marchandises |
| ------------ | ------------------------------------------- |
| `statusCode` | Le code d'état HTTP, répété dans le corps. |
| `code` | Un code d'erreur stable et lisible par machine. |
| `message` | Une description lisible par l'homme, sûre à enregistrer. |

#### Codes d'état

| État | Quand ça arrive |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request` | Un champ obligatoire est manquant ou invalide, par exemple. `action` omis à un point de contrôle, ou `tool_name` omis sur une `tool_call` Scanner. |
| `401 Unauthorized` | La clé API est manquante, mal formée, révoquée ou utilisée à partir d'une IP refusée. |
| `403 Forbidden` | La clé est valide mais n'a pas la portée requise. |
| `404 Not Found` | La ressource référencée (p. ex. un ID de point de contrôle) n'existe pas dans cet espace de travail. |
| `429 Too Many Requests` | La limite de taux a été dépassée. Honorez la `Retry-After` en-tête. |
| `500` | Une erreur de serveur inattendue. Les `message` est générique; réessayez avec backoff. |

### Limites tarifaires

L'API impose une **fenêtre coulissante, par clé** limite.

* **Par défaut & #160;:** 600 requêtes par minute par clé API.
* **Réponse en cas de dépassement:** `429 Too Many Requests` avec une `Retry-After` en-tête (secondes à attendre).

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

#### Étiquette de sondage

Lors du vote sur un point de contrôle avec `GET /v1/checkpoints/{id}`, gardez une **minimum de 1 seconde** entre les bureaux de scrutin d'un même point de contrôle — un scrutin plus serré est rejeté. Préférez le paramètre long-poll `GET /v1/checkpoints/{id}/wait`, qui maintient la connexion ouverte et retourne dès que l'état change, de sorte que vous faites beaucoup moins de demandes.

### Idempotency

Écrire les paramètres (`POST /v1/checkpoints`, `POST /v1/secure/scan`) accepter une option `Idempotency-Key` l'en-tête pour que les relevés soient sûrs:

```
Idempotency-Key: 4f1e9c2a-7b3d-4a1f-9c8e-2d6b0a5f1e33
```

Réutiliser la même clé avec un **différent** l'organisme de demande est rejeté — une clé est liée à la charge utile avec laquelle elle a été vue pour la première fois. Utilisez un UUID frais par opération logique, et réutilisez-le seulement lors de la réessayer cette opération exacte.