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é :

{
  "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.