Documentation/Gestion des erreurs

Gestion des erreurs

Ce guide présente le format des réponses d'erreur de l'API 诺玛AI, les scénarios d'erreur courants ainsi que les stratégies de traitement recommandées.

Format des réponses d'erreur#

Toutes les réponses d'erreur suivent un format JSON unifié :

Code

{
  "error": {
    "code": "invalid_api_key",
    "message": "La clé API fournie est invalide, veuillez vérifier et réessayer.",
    "type": "authentication_error"
  }
}

Codes de statut HTTP#

Code de statut

Type

Description

Réessayer ?

`400`

`invalid_request_error`

Erreur de paramètre de requête

❌ Corriger les paramètres

`401`

`authentication_error`

API Key invalide ou absente

❌ Vérifier l'API Key

`403`

`permission_error`

Permissions insuffisantes

❌ Vérifier les permissions du compte

`404`

`not_found_error`

Modèle ou ressource introuvable

❌ Vérifier l'ID du modèle

`429`

`rate_limit_error`

Limite de débit atteinte

✅ Attendre puis réessayer

`500`

`internal_error`

Erreur interne du serveur

✅ Réessayer plus tard

`502`

`upstream_error`

Erreur du fournisseur de modèle en amont

✅ Changer de modèle ou réessayer

`503`

`service_unavailable`

Service temporairement indisponible

✅ Réessayer plus tard

Erreurs courantes et solutions#

401 — API Key invalide

Code

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Solutions :

Vérifiez que l'API Key est correctement copiée (avec le préfixe `sk-`)
Confirmez que la Key n'a pas expiré et n'est pas désactivée
Vérifiez que les variables d'environnement sont correctement chargées

429 — Limite de débit

Solutions :

Vérifiez `x-ratelimit-reset-requests` dans les en-têtes de réponse
Mettez en place une nouvelle tentative avec backoff exponentiel
Si vous avez besoin d'un quota plus élevé, contactez le support pour demander un ajustement

502 — Erreur en amont

Solutions :

Utilisez le repli (fallback) pour basculer automatiquement vers un modèle de secours
Réessayez plus tard
Consultez la page de statut du fournisseur de modèles

Stratégie de nouvelle tentative#

Il est recommandé d'utiliser une stratégie de **backoff exponentiel (Exponential Backoff)** :

Code

import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<你的 APINOMA_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Wrapper de réessai avec backoff exponentiel"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: attendre puis réessayer
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Limite de débit atteinte, attente de {wait:.1f}s avant réessai...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Erreur réseau : courte attente puis réessai
            wait = 2 ** attempt
            print(f"Erreur de connexion, attente de {wait}s avant réessai...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx : erreur serveur, réessai
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx : erreur client, pas de réessai
                raise

    raise Exception(f"Échec après {max_retries} tentatives")

# Utilisation
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Bonjour"}]
)

Configuration du délai d'expiration#

Il est conseillé de définir un délai d'expiration raisonnable pour les appels API :

Code

# Python OpenAI SDK
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<你的 APINOMA_API_KEY>",
    timeout=60.0,  # Délai de 60 secondes
    max_retries=3  # Réessais intégrés au SDK
)

Pour les requêtes en streaming, il est recommandé d'utiliser un délai plus long (120 à 300 secondes), car le modèle peut avoir besoin de plus de temps pour générer l'intégralité du contenu.

Bonnes pratiques#

Distinguer les erreurs réessayables des non-réessayables — les 4xx nécessitent généralement une correction de la requête, les 5xx peuvent être réessayées
Utiliser le backoff exponentiel — éviter les réessais fréquents en cas de limitation de débit
Définir un nombre maximum de tentatives — éviter les boucles infinies
Enregistrer les journaux d'erreurs — facilite le débogage
Configurer le repli automatique — utiliser le paramètre `provider.fallback` de 诺玛AI pour basculer automatiquement vers un autre modèle
Surveiller le taux d'erreurs — suivre les tendances d'erreurs dans la console

Dernière mise à jour le 23 juin 2026