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.

Veyra Docs TeamMis à jour le 2 min de lectureVersion 2 · Historique

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.

JSON
{
  "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é :

JSON
{
  "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-After sur un 429.
  • Reculent de façon exponentielle, avec une part aléatoire, sur les 5xx et 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.
APIDéveloppeursErreursLimites de débit