Erreurs et limites

Format des erreurs#

Les erreurs sont renvoyées avec un statut HTTP hors 2xx et un corps JSON contenant un champ error. Selon l'origine de l'erreur, error est une chaîne ou un objet :

Contrôles de la passerelle : une chaîne#

Validation, authentification, solde insuffisant et erreurs internes :

{  "error": "Missing required fields: model, messages"}

Plafonds de clé et erreurs du fournisseur : un objet#

Les plafonds mensuels par clé et les erreurs transmises par le fournisseur du modèle utilisent l'objet de style OpenAI avec message et un code :

{  "error": {    "message": "Monthly spend limit reached for this API key",    "type": "insufficient_quota",    "code": "key_monthly_limit"  }}

{  "error": {    "message": "Rate limit exceeded, please retry shortly",    "code": 429  }}

Gérez les deux formes si vous analysez les erreurs vous-même :

// Works for both error shapes returned by Promptixfunction errorMessage(body) {  if (typeof body?.error === 'string') return body.error;  return body?.error?.message ?? 'Unknown error';} const res = await fetch('https://promptix.tn/api/v1/chat/completions', { /* ... */ });if (!res.ok) {  const body = await res.json().catch(() => null);  const code = typeof body?.error === 'object' ? body.error.code : undefined;  throw new Error(`${res.status}${code ? ` ${code}` : ''}: ${errorMessage(body)}`);}

Codes de statut#

Crédits insuffisants#

Une requête n'est acceptée que si votre solde est d'au moins 0,100 TND à son démarrage. Sinon :

{  "error": "Insufficient credits. Please top up your account."}

Le coût d'une requête est déduit une fois celle-ci terminée : une longue requête lancée avec un petit solde peut donc le faire passer légèrement sous zéro. Rechargez pour continuer ; les requêtes fonctionnent à nouveau dès la confirmation du paiement. Promptix vous envoie un e-mail lorsque votre solde passe sous 5 TND, pour que vous puissiez recharger avant d'en arriver là (cette alerte se désactive dans Paramètres).

Plafond mensuel de clé atteint#

Lorsqu'une clé a un plafond mensuel et que ses dépenses depuis le premier jour du mois (UTC) l'ont atteint, les requêtes avec cette clé renvoient 402 avec "code": "key_monthly_limit" et "type": "insufficient_quota". Rien n'est facturé. Relevez ou supprimez le plafond dans Clés API, utilisez une autre clé ou attendez le mois suivant. Détails dans Authentification.

Limites de débit#

Promptix n'impose pas de limite de requêtes par minute. Le débit est limité par le fournisseur de chaque modèle : lorsqu'il vous freine, vous recevez son 429. Les modèles gratuits ont des limites beaucoup plus strictes que les modèles payants.

• Réessayez les réponses 429 et 5xx avec un délai exponentiel et un peu d'aléa (par exemple 1 s, 2 s, 4 s, puis abandon).
• Ne réessayez pas les 400, 401, 402, 404, 413 ou 422 : la même requête échouera à nouveau.
• Pour les traitements en masse, limitez la concurrence (quelques requêtes en parallèle) plutôt que de tout envoyer d'un coup.
• Si un modèle reste limité, basculez vers un modèle équivalent d'un autre fournisseur.

Erreurs pendant le streaming#

Les erreurs détectées avant le début d'un flux utilisent les codes ci-dessus. Si le fournisseur échoue après le début du streaming, le statut est déjà 200 ; Promptix envoie un dernier événement et ferme le flux sans data: [DONE] :

data: {"error":{"message":"Streaming failed","type":"stream_error"}}

Voir Streaming.

Gérer les erreurs avec les SDK OpenAI#

Les SDK lèvent des exceptions typées selon le statut HTTP et réessaient automatiquement les réponses 408, 409, 429 et 5xx (deux fois par défaut). Un 402 n'est pas réessayé.

import osimport openaifrom openai import OpenAI client = OpenAI(    base_url="https://promptix.tn/api/v1",    api_key=os.environ["PROMPTIX_API_KEY"],    max_retries=3,  # retries 408, 409, 429 and 5xx with exponential backoff    timeout=120,) try:    completion = client.chat.completions.create(        model="openai/gpt-6-luna",        messages=[{"role": "user", "content": "Hello"}],    )except openai.AuthenticationError:    print("401: check PROMPTIX_API_KEY")except openai.RateLimitError:    print("429: the provider is throttling, retry later")except openai.APIStatusError as e:    if e.status_code == 402:        body = e.response.json()        err = body.get("error")        if isinstance(err, dict) and err.get("code") == "key_monthly_limit":            print("402: this key reached its monthly limit")        else:            print("402: balance too low, top up in the dashboard")    else:        print(e.status_code, e.message)

Délais d'attente#

Une requête, streaming compris, peut durer jusqu'à 300 secondes sur Promptix. Réglez le délai de votre client un peu au-dessus de la plus longue réponse attendue, et utilisez le streaming pour les longues générations afin que la connexion ne reste jamais inactive.