Dépannage de l’API compatible OpenAI : corriger les 401, les noms de modèles, le streaming et les URL de base

Le dépannage d’une API compatible OpenAI devient beaucoup plus simple lorsque vous cessez de considérer chaque requête échouée comme « le fournisseur est en panne ». La plupart des migrations ratées proviennent de l’une de six couches : la clé, l’URL de base, la famille d’endpoint, le nom du modèle, le comportement du streaming ou la facturation/la lecture des retours.

Flatkey aide les équipes à centraliser l’accès aux modèles, le routage, la facturation, les analyses d’utilisation et les contrôles opérationnels, mais un client compatible OpenAI doit tout de même être configuré avec précision. Une requête peut sembler correcte dans le SDK et échouer quand même parce que le client pointe vers la mauvaise racine /v1, que l’alias de modèle appartient à une autre famille d’endpoint, ou que le flux est mis en tampon par un proxy.

Utilisez ce guide de dépannage d’API compatible OpenAI comme chemin de débogage propre avant de modifier le code de l’application. Commencez avec curl, validez une requête non streamée, ajoutez le SDK, puis ajoutez le streaming, les outils et le trafic de production, une couche à la fois.

Le parcours de dépannage d’une API compatible OpenAI en cinq minutes

Avant d’inspecter le code du framework, capturez la plus petite requête qui devrait fonctionner. Pour Flatkey, utilisez l’URL de base affichée dans votre console actuelle. La page d’accueil publique de Flatkey affiche actuellement une requête vers https://router.flatkey.ai/v1/chat/completions, ce qui signifie que les clients SDK doivent généralement recevoir la racine /v1 comme URL de base et que le SDK doit ajouter /chat/completions.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: ok"}
    ]
  }'

Si cette requête échoue, le problème ne vient pas du framework de votre application. Corrigez d’abord la clé, l’URL de base, la famille d’endpoint ou l’alias de modèle. Si elle réussit, copiez les mêmes valeurs dans le SDK et poursuivez le débogage à partir de là.

La règle de dépannage la plus rapide pour une API compatible OpenAI est simple : ne testez pas le streaming, les outils, le mode JSON, les tentatives automatiques ou un workflow d’agent complet tant qu’une requête texte simple non streamée n’a pas réussi.

Lisez l’erreur comme une couche, pas comme un verdict

Utilisez le code de statut pour décider de ce qu’il faut modifier ensuite.

Symptôme	Couche probable	À vérifier en premier
401, invalid_api_key ou erreur d’authentification	Clé et en-tête d’authentification	Format Bearer, source de la clé, espaces copiés, clé du fournisseur versus clé du gateway
403 ou accès refusé	Compte, projet ou stratégie	Liste d’autorisation IP, appartenance au projet, approbation du modèle, autorisation de l’endpoint
404, model_not_found ou modèle inconnu	Catalogue de modèles et famille d’endpoint	Alias exact du modèle, état d’activation du modèle, /chat/completions versus /responses versus un autre endpoint
400 requête mal formée	Structure du payload	Champs requis, paramètres non pris en charge, schéma des outils, format des messages
La connexion au stream s’établit mais aucun token n’apparaît	Chemin de streaming	stream: true, analyseur SSE, proxy qui met en tampon, prise en charge du streaming par l’endpoint
La requête réussit mais l’usage est manquant	Lecture des retours et facturation	Requête de comparaison non streamée, enregistrement dans le tableau de bord, comportement de l’événement final du flux
429, 500, 502, 503 ou 504	Limite, capacité ou amont	Backoff, volume de requêtes, page d’état, politique de retry, route de secours

Le guide d’erreurs d’OpenAI lui-même considère les 401 comme des problèmes d’authentification, les 429 comme des problèmes de taux ou de quota, et les réponses 500/503 comme des conditions de serveur ou de surcharge pouvant être retentées. Une passerelle compatible OpenAI peut ajouter ses propres détails, alors conservez le corps de la réponse et l’identifiant de requête lorsque vous faites remonter le problème.

Corrigez les 401 avant de changer de modèle

Un 401 est le détour de dépannage le plus courant pour une API compatible OpenAI, car il ressemble à un problème de modèle ou de route alors qu’il s’agit généralement d’un problème d’authentification.

Vérifiez ces points dans cet ordre :

1. La requête contient exactement un en-tête Authorization: Bearer ....
2. La clé est une clé Flatkey lors d’un appel à Flatkey, et non une clé OpenAI, Anthropic, Google ou de test directe.
3. La clé ne contient ni guillemets copiés, ni saut de ligne, ni préfixe invisible, ni espace de fin.
4. La clé est chargée depuis l’environnement dans lequel votre processus s’exécute réellement, et pas seulement depuis votre shell.
5. La politique du compte, du projet, de l’équipe ou de l’adresse IP autorise la route.

Utilisez une vérification shell courte qui n’affiche pas la clé :

test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c

Si curl fonctionne mais que le SDK renvoie 401, inspectez les noms des variables d’environnement. Le client Python d’OpenAI lit OPENAI_API_KEY par défaut, et le client Node lit OPENAI_API_KEY par défaut. Si votre application exporte encore OPENAI_API_KEY avec une ancienne clé de fournisseur direct, le SDK peut ignorer votre nouvelle clé de gateway à moins que vous ne passiez api_key ou apiKey explicitement.

Corrigez l’URL de base sans dupliquer l’endpoint

Les erreurs d’URL de base se répartissent généralement en deux schémas :

1. Le SDK reçoit l’endpoint complet, tel que https://router.flatkey.ai/v1/chat/completions, puis ajoute /chat/completions à nouveau.
2. Le SDK ne reçoit que le domaine, tel que https://router.flatkey.ai, et n’atteint jamais la route compatible OpenAI /v1.

Pour Python, passez base_url ou définissez OPENAI_BASE_URL. La source officielle du client Python retombe également sur https://api.openai.com/v1 lorsqu’aucune URL de base personnalisée n’est fournie.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Répondez avec exactement : ok"}],
)

print(response.choices[0].message.content)

Pour Node, passez baseURL ou définissez OPENAI_BASE_URL. Le client Node officiel documente baseURL comme la surcharge de la racine API OpenAI par défaut.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Répondez avec exactement : ok" }],
});

console.log(response.choices[0]?.message?.content);

Si cette étape de dépannage de l’API compatible OpenAI échoue encore, consignez l’URL de base résolue au démarrage du processus. Ne consignez pas la clé.

Séparez les noms de modèles des familles d’endpoint

« Modèle introuvable » peut signifier que l’alias est incorrect, mais cela peut aussi signifier que l’alias est envoyé à la mauvaise famille d’endpoint. Un modèle qui fonctionne pour les complétions de chat peut ne pas être exposé via Responses, Messages, les images, la vidéo ou les embeddings avec la même forme de charge utile.

Exécutez cette liste de vérification avant de renommer des modèles en production :

Vérification	Pourquoi c’est important
Confirmez l’alias exact du modèle dans la console Flatkey actuelle	Les alias de la passerelle peuvent différer des noms marketing du fournisseur direct
Confirmez la famille d’endpoint	/v1/chat/completions et /v1/responses ont des formes de requête différentes
Supprimez les paramètres facultatifs	Une option non prise en charge peut masquer le vrai problème de modèle
Essayez une requête courte sans streaming	Une requête simple isole la route de l’analyse du stream
Enregistrez le corps en échec et l’horodatage	Le support et la revue d’audit ont besoin du modèle, de la route et de l’erreur exacts

La documentation externe des modèles d’OpenAI utilise la même idée pour les endpoints personnalisés : fournissez une URL d’endpoint, spécifiez des slugs de modèle et exécutez un appel de vérification. Traitez la configuration de votre passerelle de la même manière. Conservez dans le code une petite cartographie des modèles approuvés au lieu de laisser chaque service utiliser des chaînes de modèle brutes.

Déboguez le streaming après que le non-streaming fonctionne

Le streaming doit être un test de deuxième étape. La référence Chat Completions d’OpenAI renvoie soit un objet de complétion de chat JSON, soit une séquence diffusée d’objets de fragments de complétion de chat. L’API Responses prend également en charge text/event-stream lorsque stream est activé.

Utilisez une sonde de stream directe :

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Comptez lentement de un à cinq."}
    ]
  }'

Si la requête sans streaming fonctionne et que le stream échoue, inspectez le chemin du stream :

• Confirmez que la réponse utilise un type de contenu compatible SSE.
• Désactivez le middleware du client API qui met en mémoire tampon toute la réponse avant de la renvoyer.
• Désactivez la mise en tampon du proxy inverse pour cette route.
• Vérifiez si votre analyseur frontend attend des fragments Chat Completions alors que votre route renvoie des événements Responses.
• Comparez avec la checklist de streaming Flatkey existante à /blog/openai-compatible-streaming-sse-test.

Cette étape de dépannage de l’API compatible OpenAI est particulièrement importante dans les outils serverless et d’automatisation. Certains wrappers renvoient un statut HTTP réussi tout en masquant le fait qu’aucun jeton n’a atteint l’appelant avant la fermeture du stream.

Ajoutez les outils uniquement après que la requête de base est propre

L’appel d’outils ajoute un autre niveau d’échec. Une passerelle, une route ou un modèle sélectionné peut accepter des messages de chat simples mais rejeter un schéma d’outil, tool_choice, des appels d’outils parallèles ou des paramètres de sortie structurée stricte.

Utilisez une échelle en trois requêtes :

1. Requête de texte simple avec le même modèle.
2. Même requête avec un petit schéma de fonction.
3. Schéma d’outil complet de production.

Si la requête 1 fonctionne et que la requête 2 échoue, vous ne dépannez plus l’authentification ni l’URL de base. Vous dépannez les capacités du modèle, la famille d’endpoint ou la prise en charge du schéma. Supprimez les champs facultatifs, raccourcissez les descriptions et vérifiez si la route du modèle sélectionnée prend en charge le comportement d’outil dont vous avez besoin.

Prouvez la lecture de l’usage et de la facturation

Ne terminez pas le dépannage de l’API compatible OpenAI au simple constat que « la réponse a renvoyé du texte ». Pour une migration en production, vous devez aussi prouver que la requête est visible là où les équipes finances et opérations la consulteront.

Après un test de fumée réussi, capturez :

Preuve	Ce qu’elle prouve
Horodatage et route de la requête	Quel chemin de passerelle a reçu le trafic
Alias du modèle	Quel modèle configuré a été demandé
Statut de la réponse et ID de requête	Ce que l’assistance peut retracer
Objet d’utilisation ou nombre de jetons	Si l’application peut enregistrer les facteurs de coût
Lecture du tableau de bord ou de la facturation	Si les finances peuvent rapprocher les dépenses
Événement de repli ou de nouvelle tentative, le cas échéant	Si la politique de routage a modifié le chemin

Flatkey est positionné autour d’une clé unique, d’une tarification claire, d’une facturation unifiée et d’un tableau de bord pour les clés, l’utilisation et le routage. Pour une migration, associez le test de fumée d’ingénierie à un contrôle de lecture de l’utilisation dans la console avant de déplacer du trafic réel.

Un workflow de dépannage sûr pour la production

Utilisez cette séquence lorsqu’une migration vers une API compatible OpenAI échoue :

1. Exécutez une requête curl non streamée avec l’URL de base actuelle de la console, une clé et un alias de modèle approuvé.
2. Corrigez toute erreur 401 ou 403 avant de modifier les charges utiles.
3. Corrigez la composition de l’URL de base avant de modifier les versions du SDK.
4. Corrigez l’alias du modèle et la famille de points de terminaison avant de modifier la politique de nouvelle tentative.
5. Ajoutez le SDK avec api_key ou apiKey explicite et base_url ou baseURL.
6. Ajoutez le streaming et vérifiez que le client reçoit des événements incrémentaux.
7. Ajoutez les outils ou la sortie structurée une fonctionnalité à la fois.
8. Vérifiez l’utilisation et la lecture de la facturation.
9. Déplacez les valeurs fonctionnelles dans une configuration prête pour le rollback.

Cet ordre évite que le dépannage d’une API compatible OpenAI ne se transforme en séance de devinettes. Chaque étape prouve soit une couche, soit vous donne une défaillance plus petite à corriger.

Quand Flatkey aide

Flatkey est utile lorsque le problème racine est une dispersion opérationnelle : trop de clés de fournisseurs, un accès aux modèles incohérent, une utilisation difficile à examiner et des chemins de facturation séparés. Une passerelle unifiée ne supprime pas la nécessité de tester la famille de points de terminaison, l’alias du modèle, le streaming, les outils et la lecture de la facturation, mais elle donne à l’équipe un endroit unique pour standardiser ces vérifications.

Si vous migrez une application, associez ce guide au guide de migration Flatkey compatible OpenAI à l’adresse /blog/openai-compatible-api-migration et à la checklist de test de fumée à l’adresse /blog/ai-api-smoke-test-checklist.

Lorsque vous êtes prêt à tester le workflow avec une clé Flatkey, commencez à /sign-up et gardez le premier test de fumée suffisamment petit pour être inspecté à la main.

Questions fréquentes

Pourquoi mon API compatible OpenAI renvoie-t-elle une erreur 401 lorsque la clé est définie ?

Le processus peut lire une variable d’environnement différente de celle que vous avez modifiée, ou la clé peut appartenir au mauvais fournisseur. Vérifiez le nom de la variable résolue, l’en-tête Authorization: Bearer, les espaces copiés et toute politique de compte ou d’adresse IP.

L’URL de base du SDK doit-elle inclure /chat/completions ?

En général non. Fournissez au SDK l’URL de base /v1, puis laissez le SDK ajouter le point de terminaison. Passer le point de terminaison complet crée souvent des chemins dupliqués.

Pourquoi un modèle fonctionne-t-il sans streaming mais échoue-t-il avec stream: true ?

La route de base peut être correcte tandis que le chemin de streaming est bloqué par un middleware de buffering, une incompatibilité du parseur SSE ou une combinaison route/modèle qui ne prend pas en charge le streaming. Testez avec curl -N avant de déboguer le code frontend.

Pourquoi « model not found » se produit-il avec un nom de modèle valide ?

L’alias peut être valide dans une famille de points de terminaison et invalide dans une autre, ou la passerelle peut exposer un alias différent de celui du fournisseur direct. Confirmez ensemble l’alias actuel de la console et la famille de points de terminaison.

Que dois-je tester avant d’envoyer du trafic de production ?

Testez une requête non streamée, une requête SDK, un stream, un appel d’outil représentatif si votre application utilise des outils, un chemin d’échec et un enregistrement de facturation/lecture. Conservez ensuite une configuration de rollback pour l’ancienne route du fournisseur.

Le dépannage d’une API compatible OpenAI ne consiste pas à mémoriser toutes les erreurs de chaque fournisseur. Il s’agit de prouver le chemin depuis la clé jusqu’à l’URL de base, de l’URL de base à la famille de points de terminaison, de la famille de points de terminaison à l’alias du modèle, et de la réponse réussie à l’enregistrement d’utilisation. Lorsque ces couches sont claires, le basculement du trafic via Flatkey devient une migration maîtrisée plutôt qu’une session de débogage tard dans la nuit.