Erreurs et limites

Toute erreur /v1, quelle que soit la route, prend la même forme, jamais une page HTML ni une trace :

{
  "error": { "type": "invalid_request", "code": "invalid_parameter", "message": "instructions must be a string of at most 20000 characters.", "param": "instructions" },
  "request_id": "req_01k6examplereq00000000000"
}

param n'apparaît que lorsqu'un champ précis est en cause. request_id est toujours présent, voir Authentification.

Types et codes rencontrés

Échec d'un run

Un run terminé failed porte error: {"code": "...", "message": "..."}. Le message ne contient jamais le texte brut d'un fournisseur d'IA. Le code indique la conduite à tenir :

Les trois derniers codes concernent les runs avec un schéma de sortie : les crédits déjà consommés restent débités ; seuls les appels de mise en forme et de correction réellement servis sont facturés, voir Sortie structurée.

Outils client

Bornes propres aux outils client : 20 par agent, 20 par run, 1 024 caractères de description, 16 384 octets de parameters, 100 000 octets par résultat de tool_outputs, et 10 minutes d'attente au plus d'un run en requires_action.

Avertissements de widget

Un run lancé par un widget peut porter, dans warnings :

• client_tool_unreachable : le widget n'a pas d'URL de webhook, ou l'organisation pas de secret de webhook ; l'outil client server est écarté du run.
• widget_tool_unavailable : un outil qui donnerait accès aux données leem ou à un serveur MCP est retiré du run (un widget ne les porte pas).

Les codes propres aux routes navigateur du widget (invalid_session, origin_not_allowed, user_rate_limited…) sont listés dans Widget.

Débit de requêtes

120 requêtes par minute et par clé API par défaut (peut être ajusté par organisation ou par formule). Chaque réponse d'une requête authentifiée et admise porte X-RateLimit-Limit et X-RateLimit-Remaining (pas une réponse 401 ou 429, ni le téléchargement signé GET /v1/files/{file}/content) ; au-delà, 429 too_many_requests avec un en-tête Retry-After en secondes.

Runs simultanés

5 runs actifs (queued ou running) au plus par organisation par défaut ; la limite est propre à chaque organisation (fixée par sa formule, ou ajustée pour elle). Un run en requires_action (en attente des résultats d'un outil client) n'est pas compté. Un POST /v1/runs qui dépasserait cette limite reçoit 429 concurrent_runs_exceeded avec Retry-After.

Crédit disponible

Les runs se paient en crédits, à l'usage : d'abord le crédit mensuel de la formule, puis les crédits supplémentaires. POST /v1/runs vérifie que l'organisation a encore du crédit (credit.available dans GET /v1/organization) ; sinon la requête est refusée en 402 insufficient_credits : aucun run n'est créé.

Un run lancé s'arrête automatiquement quand le crédit est épuisé : il passe en failed avec l'erreur insufficient_credits, et les fichiers et graphiques déjà produits sont conservés. Le dépassement est borné à un tour du modèle. Achetez des crédits supplémentaires depuis la page Consommation de votre espace (/parametres/consommation) ou attendez le renouvellement mensuel, puis relancez le run.

Idempotence

Tout POST /v1 accepte un en-tête Idempotency-Key (1 à 255 caractères), propre à votre organisation, conservé 24 heures :

• Rejouer la même requête (même méthode, même chemin, même corps) sous la même clé renvoie la réponse déjà produite, avec Idempotent-Replayed: true : l'action n'est jamais refaite.
• Rejouer un flux SSE sous la même clé (POST /v1/runs avec stream: true) rouvre un flux sur le même run, repris depuis votre Last-Event-ID.
• Utiliser la même clé avec un corps différent est refusé (409 idempotency_key_reused).
• Une requête encore en cours sous cette clé refuse une seconde requête concurrente (409 idempotency_key_in_progress).
• Une réponse qui montrait un secret une seule fois (rotation du secret de webhook) n'est jamais rejouée (409 idempotency_key_sensitive_replay) : renvoyez sans Idempotency-Key pour une nouvelle tentative.
• Une réponse 402, 409, 429 ou 5xx ne réserve jamais la clé : elle reste libre pour un nouvel essai immédiat.

Versionnement

/v1 n'ajoute que des points d'entrée et des champs ; à partir de la 1.1, rien n'en est retiré ni renommé. Un client tolérant aux champs qu'il ne connaît pas encore reste compatible sans changement de version.

Historique :

• 1.5 (2026-11-01) : équipe d'agents du widget. Ajout facultatif : le champ agents de POST /v1/widgets/{widget}/sessions, dans le corps et dans la réponse. Sans lui, une session a accès à toute l'équipe du widget. Voir Widget.
• 1.4 (2026-10-31) : widget et documents de connaissance. Ajouts facultatifs : GET/POST /v1/agents/{agent}/documents, DELETE /v1/agents/{agent}/documents/{file}, POST /v1/widgets/{widget}/sessions, DELETE /v1/widget_users/{id}, les champs execution et label des outils client, les avertissements client_tool_unreachable et widget_tool_unavailable, les codes too_many_documents, file_in_use et widget_unavailable. Voir Widget.
• 1.3 (2026-10-30) : outils client. Ajouts facultatifs : client_tools (agents et runs), statut requires_action et required_action sur le run, événement SSE et webhook run.requires_action, POST /v1/runs/{run}/tool_outputs, les codes invalid_client_tool, client_tool_name_taken, run_not_waiting, unknown_tool_call, duplicate_tool_output, missing_tool_outputs, tool_output_too_large et l'erreur de run tool_outputs_timeout. Aussi : is_test sur les modèles et l'erreur de run free_model_quota (modèles de test gratuits, organisations de test uniquement). Un client qui ignore ces ajouts continue de fonctionner tant que ses agents n'en déclarent pas. Voir Outils client.
• 1.2 (2026-10-26) : sortie structurée garantie. Ajouts facultatifs : output_schema (agents et runs), output.json et output_schema sur le run, structured_output sur les modèles, 422 output_schema_unsupported et trois codes d'échec de run. Voir Sortie structurée.
• 1.1 (2026-10-24) : balance devient credit ; usage.cost (MGA) devient usage.credits. La règle « rien n'est retiré ni renommé » s'applique à partir de la 1.1.