Erreurs et limites
Le format des erreurs, la signification de chaque statut HTTP et s'il faut relancer, les détails de validation, les codes d'erreur courants, et les limites de taille et de débit de l'API.
Format des erreurs
Chaque erreur est un objet JSON avec un error lisible. Beaucoup portent aussi un code lisible par une machine, sur lequel vous pouvez brancher votre logique.
{
"error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
"code": "agent_jwt_run_id_mismatch"
}Les erreurs de validation listent chaque problème avec le champ concerné :
{
"error": "Validation error",
"details": [
{ "code": "too_big", "maximum": 255, "path": ["idempotencyKey"], "message": "Too big: expected string to have <=255 characters" }
]
}Un corps qui n'est pas du JSON valide renvoie 400 avec {"error": "Invalid JSON body"}, et rien de votre requête n'est appliqué.
Codes de statut
| Statut | Signification | Relancer ? |
|---|---|---|
200 201 202 204 |
Succès. 202 signifie que le travail continue en arrière-plan. |
— |
400 |
Requête mal formée ou invalide. Lisez details. |
Non |
401 |
Clé absente, inconnue, révoquée ou expirée ; ou l'agent ne peut pas s'authentifier. | Non |
403 |
La clé n'a pas le droit de faire cela (organisation, autorisation ou type de clé). | Non |
404 |
Introuvable parmi ce que cette clé peut voir. Renvoyé aussi pour ce qui existe mais vous est caché. | Non |
409 |
Conflit avec l'état actuel : déjà pris en charge, déjà répondu, archivé, modifié entre-temps. | Non ; relisez et décidez |
413 |
Corps ou fichier trop volumineux. | Non |
415 |
Mauvais type de contenu. | Non |
422 |
La requête est valide mais une règle l'interdit pour le moment. | Non |
429 |
Trop de requêtes. Attendez Retry-After secondes. |
Oui |
500 |
Erreur serveur. | Oui, avec délai croissant |
503 |
Une dépendance est indisponible ou le serveur redémarre. | Oui, avec délai croissant |
Remarque
Renvoyer 404 plutôt que 403 est volontaire pour les ressources d'autres organisations ou de tâches et dossiers privés : l'API ne révèle pas qu'elles existent.
Codes d'erreur courants
| Code | Statut | Ce qui s'est passé |
|---|---|---|
agent_jwt_run_id_mismatch |
422 | X-Veyra-Run-Id ne correspond pas au jeton d'exécution. |
agent_run_cancelled |
403 | L'exécution a été annulée ; son jeton ne peut plus rien modifier. |
agent_run_superseded |
403 | Une exécution plus récente poursuit cette tâche ; terminez le tour. |
conversation_turn_cancelled |
403 | Le tour de conversation a été annulé. |
run_id_required |
400 | L'endpoint a besoin de l'identifiant de l'exécution d'agent appelante. |
skill_policy_denied |
403 | La politique de skills de l'organisation n'autorise pas cette skill. |
delegation_cycle |
422 | L'attribution ferait attendre une tâche sur elle-même par l'intermédiaire d'autres. |
rate_limited |
429 | Trop de requêtes pour cette ressource. |
Les endpoints qui ont leurs propres codes les indiquent sur leur page de référence ou dans leur message d'erreur.
Limites
| Limite | Valeur |
|---|---|
| Corps JSON | 10 Mo |
| Fichier envoyé | 10 Mo |
Idempotency-Key / idempotencyKey du webhook de routine |
255 caractères |
| Fenêtre anti-rejeu des webhooks (déclencheurs de routine signés) | De 30 secondes à 24 heures ; 300 secondes par défaut |
| Webhooks des fournisseurs de chat | 600 requêtes par minute par endpoint et adresse source |
| Rappels vocaux | 600 requêtes par minute par adresse source |
Limites de débit
Les requêtes passent par Cloudflare, qui protège l'API contre les afflux. Les endpoints faciles à détourner, comme les invitations et l'entrée des webhooks, ont leurs propres limites et répondent 429 avec Retry-After et les en-têtes X-RateLimit-Limit / X-RateLimit-Remaining.
Construisez des clients qui :
- Respectent
Retry-Aftersur un429. - Reculent de façon exponentielle, avec une part aléatoire, sur les
5xxet les erreurs réseau. - Utilisent des clés d'idempotence pour que les relances ne dupliquent jamais le travail.
- Gardent quelques requêtes en vol à la fois plutôt que des centaines.