Dépannage

La plupart des problèmes se manifestent par un statut HTTP et un code dans le corps de l'erreur. Trouvez le code ci-dessous ; la page Erreurs contient la liste complète. Les requêtes en échec (tout 4xx ou 5xx) ne sont jamais facturées.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

La clé est manquante, mal formée ou révoquée.

• Envoyez-la sous la forme Authorization: Bearer sk-api14-.... Les SDK OpenAI le font à partir de apiKey / api_key ; avec curl, vérifiez que $API14_API_KEY est bien définie dans le shell d'où vous l'exécutez (echo ${API14_API_KEY:0:9} doit afficher sk-api14-).
• Attention aux guillemets ou retours à la ligne parasites quand la clé vient d'un fichier .env.
• Une variable OPENAI_API_KEY restée dans l'environnement peut remplacer la clé que vous vouliez utiliser. Passez la clé explicitement pour l'écarter.
• Une clé révoquée échoue immédiatement. Les clés ne sont affichées qu'une fois : si vous en avez perdu une, créez-en une nouvelle dans Clés d'API et révoquez l'ancienne.

Voir Authentification.

402 insufficient_balance

Votre solde en USD est à 0 $, ou (pour la vidéo) inférieur au coût estimé de la tâche. Les requêtes restent bloquées tant que vous n'ajoutez pas de fonds ; réessayer n'aide pas.

• Vérifiez le solde avec GET /credits ou dans Facturation. Voir Solde et infos de clé.
• Ajoutez des fonds ou activez la recharge automatique. Les forfaits ajoutent chaque mois une utilisation incluse au même solde. Voir Tarifs et facturation.
• Dans les tâches de longue durée, traitez ce code comme fatal et arrêtez-vous, au lieu de laisser tourner les nouvelles tentatives du SDK.

403 model_not_allowed ou plan_required

• model_not_allowed : la clé a une liste de modèles autorisés qui n'inclut pas cet identifiant de modèle. Modifiez la liste de la clé dans Clés d'API, ou utilisez une clé sans liste. Les suffixes de variante comptent : vérifiez que l'identifiant exact que vous envoyez est autorisé.
• plan_required : votre forfait n'inclut pas cette catégorie de modèles. Les forfaits standard couvrent toutes les catégories ; vérifiez votre forfait sur la page des tarifs.

404 model_not_found ou not_found

• model_not_found : l'identifiant du modèle est inconnu, désactivé ou retiré. Les identifiants incluent le préfixe du fournisseur : openai/gpt-5-mini, pas gpt-5-mini. Retrouvez l'identifiant exact avec GET /models ou GET /models/{id} (aucune clé nécessaire). Voir Identifiants et variantes de modèles.
• not_found : le chemin n'existe pas, ou la tâche vidéo ou l'identifiant de génération n'est pas le vôtre. Cela signifie généralement une mauvaise URL de base (voir ci-dessous). Une consultation de génération juste après une requête peut aussi renvoyer 404 pendant quelques secondes, le temps que l'enregistrement apparaisse.

Mauvaise URL de base

L'URL de base est exactement :

https://api14.com/api/v1

Erreurs courantes :

Particularités des bibliothèques : ruby-openai ajoute v1 lui-même, donc son uri_base est https://api14.com/api (Ruby) ; openai-go attend une barre oblique finale, https://api14.com/api/v1/ (Go).

429 rate_limited

Vous avez dépassé la limite de requêtes par minute de votre clé ou de votre forfait (Free 5, Pro 100, Team 3 000, Enterprise 3 000+). La réponse inclut Retry-After: 60.

• Attendez Retry-After et réessayez avec un backoff exponentiel et du jitter. Les SDK officiels d'OpenAI le font déjà (deux tentatives par défaut ; augmentez maxRetries / max_retries).
• Pour le travail en masse, cadencez les requêtes au lieu de toutes les lancer d'un coup, et mettez plusieurs éléments dans une requête. Voir Guide : traitement par lots.
• Un 429 peut aussi venir du fournisseur en amont, surtout sur les variantes :free. Utilisez les modèles de secours ou le routage des fournisseurs pour répartir la charge.

429 daily_limit_reached

La clé a atteint sa limite de dépense quotidienne en USD. Réessayer n'aide pas avant le prochain jour UTC. Augmentez ou supprimez la limite dans Clés d'API si le trafic est attendu. Veillez à ce que votre logique de nouvelle tentative distingue ce code de rate_limited, sinon les tâches réessaient pour rien. Voir Limites de débit.

Délais d'attente

Les grands modèles, les modèles de raisonnement et les longues sorties peuvent prendre plusieurs minutes.

• Vérifiez le délai d'attente de votre client. Les SDK Node et Python utilisent 10 minutes par défaut ; d'autres clients HTTP ont souvent des valeurs plus courtes.
• Diffusez les longues générations en streaming. Les tokens commencent à arriver en quelques secondes et les délais d'inactivité des proxys et des répartiteurs de charge cessent d'être un problème. Voir Streaming.
• Définissez max_tokens et, pour les modèles de raisonnement, un effort de raisonnement plus faible.
• Si vous relayez les requêtes via votre propre serveur, les délais de son proxy (par exemple proxy_read_timeout de nginx, 60 secondes par défaut) s'appliquent aussi.
• Un délai dépassé de votre côté n'annule pas la génération en amont, qui peut quand même être facturée. Utilisez la consultation d'une génération avec l'identifiant de la requête pour vérifier.

Le streaming se déconnecte ou s'arrête tôt

• Vérifiez finish_reason sur le dernier fragment. "length" signifie que max_tokens a été atteint ; "error" signifie que le fournisseur a échoué en cours de flux, et le fragment contient un objet error. Réessayez, ou ajoutez des solutions de secours.
• Les proxys et les plateformes serverless mettent parfois en mémoire tampon ou coupent les réponses SSE. Désactivez la mise en tampon (X-Accel-Buffering: no sur nginx) et vérifiez la durée maximale de réponse de la plateforme.
• Si vous analysez le flux vous-même, ignorez les lignes de commentaire commençant par : (keep-alive) et arrêtez-vous à data: [DONE].
• Fermer la connexion plus tôt n'annule pas la facturation : le fournisseur peut quand même terminer la génération.

Erreurs CORS et applications dans le navigateur

Ne mettez jamais de clé d'API dans du code de navigateur ou mobile. N'importe qui peut la lire dans la page et dépenser votre solde. Appelez api14 depuis votre propre backend et n'exposez que votre propre endpoint au navigateur :

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // validez et limitez cette entrée
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Une erreur CORS dans le navigateur pendant le développement vient généralement d'une mauvaise URL de base (la requête a atteint le site web au lieu de l'API) ou d'un en-tête de requête personnalisé que le preflight de l'API n'autorise pas ; déplacer l'appel vers votre serveur règle les deux.

Problèmes de version du SDK

• Python openai avant la 1.0 utilise openai.ChatCompletion.create et openai.api_base. Mettez à jour avec pip install -U openai et utilisez le client OpenAI(base_url=..., api_key=...).
• chat.completions.parse absent : les anciennes versions 1.x/4.x n'ont que client.beta.chat.completions.parse. Mettez le paquet à jour.
• Erreurs de paramètre inconnu du SDK pour les champs de la passerelle (provider, models, reasoning, plugins) : passez-les avec extra_body en Python, ou l'option équivalente de corps supplémentaire dans les autres SDK. Voir Compatibilité avec le SDK OpenAI.
• 400 du fournisseur avec un message de sa part : le paramètre n'est pas pris en charge par ce modèle ou ce fournisseur. Vérifiez les supported_parameters du modèle dans Modèles, ou ajoutez provider: { "require_parameters": true }.