API cloud
Erreurs et limites de débit
Format des erreurs, codes de statut et en-têtes de limite de débit de l’API cloud de zn.
Les erreurs renvoient du JSON avec un message dans error. Les erreurs de quota ajoutent un code lisible par machine.
{"error": "Invalid API key"}{"error": "Monthly call limit reached", "code": "MONTHLY_LIMIT_REACHED"}Codes de statut
| Statut | Signification | Que faire |
|---|---|---|
| 400 | Le corps ne contient pas input, ou input dépasse 20 000 caractères |
Envoyez {"input": "..."} et découpez les entrées longues |
| 401 | Clé d’API absente ou invalide | Vérifiez l’en-tête Authorization et la clé dans le tableau de bord |
| 429 | Limite mensuelle atteinte (MONTHLY_LIMIT_REACHED) |
Attendez la durée indiquée par Retry-After, ajoutez des crédits ou changez de plan |
| 500 | Échec inattendu de l’analyse | Réessayez une fois avec un délai (chaque requête est décomptée du quota) |
Basez votre logique sur le statut HTTP et sur code, pas sur le texte de error, qui peut changer.
En-têtes de limite de débit
RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset sont renvoyés sur les réponses réussies ainsi que sur les 401 et 429, pour que vous puissiez ralentir avant d’atteindre un 429. Un 429 inclut aussi Retry-After.
Fail open ou fail closed ?
Décidez de ce que fait votre agent quand zn est injoignable. Pour les outils à fort impact (shell, paiements, suppression de données), choisissez fail closed : n’exécutez pas l’outil. Pour les lectures à faible impact, vous pouvez choisir fail open et garder les règles locales de zn-gate en secours.