Passer au contenu principal

Format de réponse d’erreur

Toutes les erreurs renvoient un format JSON cohérent avec des Agent-First hints facultatifs :
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "did_you_mean": "suggested_model",
    "suggestions": [{"id": "model-id"}],
    "hint": "Next step guidance",
    "retryable": true,
    "retry_after": 30
  }
}
Les champs de base (message, type, code, param) sont toujours présents. Les champs d’indice (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) sont des extensions optionnelles pour l’auto-correction des agents IA. Voir le Agent-First API guide pour plus de détails. Les endpoints compatibles OpenAI utilisent les types d’erreur stables du gateway de LemonData. Les endpoints compatibles Anthropic et Gemini utilisent leurs propres familles d’erreurs natives et formats de réponse.

Codes d’état HTTP

CodeDescription
400Requête incorrecte - Paramètres invalides
401Non autorisé - Clé API manquante ou invalide
402Paiement requis - Solde insuffisant
403Interdit - Accès refusé ou modèle non autorisé
404Non trouvé - Modèle ou ressource introuvable
413Charge utile trop volumineuse - Taille d’entrée ou de fichier dépassée
429Trop de requêtes - Limite de débit dépassée
500Erreur interne du serveur
502Mauvaise passerelle - Erreur du fournisseur en amont
503Service indisponible - Service temporairement indisponible
504Délai d’attente de la passerelle - Requête expirée

Types d’erreurs

Erreurs d’authentification (401)

TypeCodeDescription
invalid_api_keyinvalid_api_keyLa clé API est manquante ou invalide
expired_api_keyexpired_api_keyLa clé API a été révoquée
from openai import OpenAI, AuthenticationError

try:
    response = client.chat.completions.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

Erreurs de paiement (402)

TypeCodeDescription
insufficient_balanceinsufficient_balanceLe solde du compte est trop faible (endpoints compatibles OpenAI)
insufficient_balance_errorinsufficient_balanceLe solde du compte est trop faible (endpoints compatibles Anthropic)
quota_exceededquota_exceededLimite d’utilisation de la clé API atteinte
from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        print("Please top up your account balance")

Erreurs d’accès (403)

TypeCodeDescription
access_deniedaccess_deniedAccès à la ressource refusé
access_deniedmodel_not_allowedModèle non autorisé pour cette clé API
{
  "error": {
    "message": "You don't have permission to access this model",
    "type": "access_denied",
    "code": "model_not_allowed"
  }
}

Erreurs de validation (400)

TypeDescription
invalid_request_errorLes paramètres de la requête sont invalides
context_length_exceededEntrée trop longue pour le modèle
model_not_foundLe modèle demandé n’est pas disponible dans le contrat public actuel
{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [{"id": "gpt-5.4"}, {"id": "gpt-5-mini"}],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}
Les routes publiques ne distinguent pas dans le corps de la réponse si un modèle est simplement mal orthographié, masqué, différé ou non public. Si un modèle n’est pas actuellement disponible via le contrat public, LemonData renvoie model_not_found.

Erreurs de limitation de débit (429)

Lorsque vous dépassez les limites de débit :
{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
En-têtes inclus :
Retry-After: 8
L’en-tête Retry-After et le champ retry_after indiquent tous deux le nombre exact de secondes à attendre avant de réessayer.

Charge utile trop volumineuse (413)

Lorsque la taille de l’entrée ou du fichier dépasse les limites :
{
  "error": {
    "message": "Input size exceeds maximum allowed",
    "type": "invalid_request_error",
    "code": "payload_too_large"
  }
}
Causes courantes :
  • Fichier image trop volumineux (max 20MB)
  • Fichier audio trop volumineux (max 25MB)
  • Le texte d’entrée dépasse la longueur de contexte du modèle

Erreurs en amont (502, 503)

TypeDescription
upstream_errorLe fournisseur a renvoyé une erreur
all_channels_failedAucun fournisseur disponible
timeout_errorLa requête a expiré
Lorsque tous les canaux échouent, la réponse inclut des modèles alternatifs :
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or switch to an available model."
  }
}

Gestion des erreurs en Python

from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.lemondata.cc/v1"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except APIConnectionError as e:
            print(f"Connection error: {e}")
            raise
        except APIError as e:
            print(f"API error: {e.status_code} - {e.message}")
            raise

Gestion des erreurs en JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: 'gpt-4o',
        messages
      });
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          continue;
        }
      }
      throw error;
    }
  }
}

Bonnes pratiques

Lorsque vous êtes limité par le débit, attendez de plus en plus longtemps entre les réessais :
wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s...
Définissez toujours des délais d’attente raisonnables pour éviter les requêtes bloquées :
client = OpenAI(timeout=60.0)  # 60 second timeout
Consignez la réponse d’erreur complète, y compris l’ID de la requête, pour le support :
except APIError as e:
    logger.error(f"API Error: {e.status_code} - {e.message}")
Certains modèles ont des exigences spécifiques (par ex., nombre maximal de tokens, formats d’image). Validez les entrées avant d’effectuer des requêtes.