Dépannage

La forme de l'erreur correspond au protocole que vous avez appelé. /v1/chat/completions et /v1/responses renvoient des erreurs au format OpenAI ; /v1/messages renvoie des erreurs au format Anthropic. Les codes de statut HTTP sont identiques pour les trois protocoles.

Format de réponse d'erreur

Format OpenAI (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Format Anthropic (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · Échec de l'authentification authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

Causes

• Aucun en-tête Authorization: Bearer (ni X-API-Key) — message : missing API key in Authorization header or X-API-Key.
• La clé ne correspond à aucune clé active — message : invalid API key.
• La clé a dépassé sa date d'expiration — message : API key expired.

Solution

1. Envoyez Authorization: Bearer sk-syn-… (ou X-API-Key: sk-syn-…).
2. Vérifiez que la clé est active dans la console et qu'elle a été copiée intégralement.

400 · Requête invalide invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

Causes

• Le champ model est absent, ou le corps JSON est vide ou mal formé.

Solution

1. Incluez un model et un corps JSON bien formé. Consultez la référence Chat Completions.

403 · Quota épuisé quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

Causes

• Le solde prépayé de la clé ou de l'espace de travail est épuisé.

Solution

1. Rechargez le solde de l'espace de travail. Remarque : Synthorai renvoie 403 quota_exhausted pour un solde épuisé, et non 429 — le backoff exponentiel n'aidera donc pas ; seul un rechargement le débloque.

403 · Conformité — pas de partage de données compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

Causes

• Votre espace de travail a no_provider_data_share activé, et le modèle demandé n'est fourni que par un fournisseur exigeant la conservation/le partage des données (p. ex. un modèle Bedrock ou Vertex en partage de données uniquement).

Solution

1. Routez la requête vers un modèle sans conservation, ou désactivez le commutateur de conformité de l'espace de travail si le partage de données est acceptable pour cette charge. La classe de conservation est un critère de routage par modèle — voir l'analyse de la conservation sur 30 jours.

429 · Débit limité rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

Causes

• Vous avez dépassé le plafond de requêtes par minute (RPM). Le message indique la limite exacte.

Solution

1. Temporisez et réessayez avec un backoff exponentiel + jitter (extrait ci-dessous). Demandez une limite plus élevée si vous avez besoin d'un débit soutenu.

502 · Aucun canal pour le modèle upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

Causes

• L'id du modèle ne correspond à aucun canal routable pour votre espace de travail — une faute de frappe, un modèle retiré ou un modèle inaccessible à votre offre.

Solution

1. Vérifiez l'id exact dans la liste des modèles en direct. Si un modèle a été récemment retiré, choisissez-en un actuel.

BYOK : erreurs du fournisseur en amont

Avec bring-your-own-key, la requête s'exécute sur votre compte fournisseur (AWS Bedrock, Google Vertex AI ou l'API Anthropic), donc Synthorai transmet l'erreur d'origine du fournisseur sans la modifier — les réponses portent usage.is_byok: true. Le correctif se trouve dans la console ou la configuration de ce fournisseur, pas dans la passerelle. Les plus courants sont les paramètres d'accès aux modèles et de partage de données au niveau du compte :

Erreurs du fournisseur en amont

Ces erreurs sont transmises par le fournisseur du modèle avec son propre statut HTTP et son type. Seuls 500 et 529 indiquent le côté fournisseur ; traitez-les (ainsi que 429) comme transitoires et réessayez, tandis que les 4xx reflètent la requête. Référence complète : la documentation des erreurs d'Anthropic.

Limites de débit

Les limites de débit sont appliquées par clé API pour garantir un usage équitable entre tous les utilisateurs.

Limites par défaut

Vous budgétisez le débit de tokens par rapport aux prix réels par token ? Passez votre charge de travail dans le calculateur de coûts d'API LLM.

Gérer les erreurs 429

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

Vous rencontrez un 502 ou une surcharge sur un modèle ? Choisissez une solution de repli dans la comparaison des prix des modèles — chaque modèle routable et son prix au token dans un seul tableau.