Erreurs et limites

Format des erreurs

Toutes les erreurs sont renvoyees dans un objet error avec:

• message
• type
• code
• request_id

Codes HTTP a connaitre

Code	Usage courant
400	requete invalide
401	bearer absent ou invalide
403	acces refuse
404	ressource ou identifiant introuvable
410	ressource devenue indisponible
413	charge trop volumineuse
429	limite de debit ou de concurrence depassee
502	erreur du fournisseur ou de l’execution du modele
503	service indisponible
504	delai d’attente du fournisseur ou de l’execution du modele

Erreurs de validation frequentes

Exemples courants:

• model n’utilise pas le format group:<uuid> ou custom:<uuid>
• messages est vide
• aucun message user n’est fourni
• temperature sort de l’intervalle autorise
• reasoning_effort utilise une valeur non prise en charge
• metadata.mode vaut orch ou synth avec une cible custom:<uuid>
• approval_id est absent lors d’une reprise

Limites de debit

L’API peut refuser des requetes avec 429 quand:

• trop d’appels sont envoyes sur une fenetre de temps donnee
• trop de requetes simultanees sont ouvertes

Sauf configuration differente, la fenetre par defaut autorise 60 requetes par 60 secondes. Les limites de concurrence par defaut sont 100 requetes ouvertes au total et 10 requetes ouvertes pour le meme token.

Votre client doit gerer ces cas avec:

• un retry controle
• du backoff
• de la limitation cote client

Gestion des erreurs SSE

En streaming, une erreur peut arriver au milieu du flux. Le client doit donc:

1. surveiller les evenements recus
2. detecter un bloc error
3. journaliser request_id
4. fermer proprement le flux

Exemple d’evenement SSE d’erreur:

data: {"error":{"message":"Stream failed","type":"api_error","code":"stream_error","request_id":"req_123"}}

data: [DONE]

Limites de taille

Limites courantes:

• corps JSON: 5 Mo par defaut
• televersement multipart: 5 Mo par defaut
• champ metadata d’un televersement: 64 Ko par defaut
• messages: 1 a 500 elements
• max_tokens et max_completion_tokens: 1 a 200000

Bonnes pratiques

• Journalisez toujours request_id.
• Validez vos payloads avant envoi.
• N’ouvrez pas trop de streams en parallele avec le meme token.
• Traitez tool_calls comme un etat distinct, pas comme une reponse texte normale.