Clé API OpenAI invalide : dépannage des erreurs 401, des variables d'environnement et de la configuration du projet

TL;DR

Quand OpenAI renvoie un 401 en indiquant que la clé est incorrecte, vérifiez d'abord les identifiants, les variables d'exécution et la configuration de l'organisation ou du projet. Pour un 429, contrôlez le débit, le solde ou la limite d'utilisation selon le code d'erreur ; pour un 403, lisez également la raison précise.

Avant d'exécuter l'exemple Python, lancez python -m pip install requests dans le même environnement Python.

Distinguez d'abord le type d'erreur

Réponse	Piste de vérification
401, avec le message Incorrect API key	Clé complète, orthographe, état de révocation et appartenance
401, autre message d'authentification	Appartenance à l'organisation, autorisations ou restrictions d'IP, etc.
403	Lisez la raison indiquée dans la réponse, y compris les restrictions régionales ou autres
429	Distinguez la limitation de débit, le solde et la limite d'utilisation de l'organisation ou du projet

Ne jugez pas la validité d'une clé uniquement à son préfixe sk-. Les identifiants complets, le domaine cible et la configuration du compte doivent tous correspondre.

Vérifier l'environnement d'exécution en cinq étapes

1. Confirmez si vous appelez OpenAI ou une plateforme compatible ; chaque plateforme utilise sa propre clé.
2. Vérifiez la variable OPENAI_API_KEY du processus réel, en écartant les valeurs vides, les espaces réservés et les copies erronées.
3. Vérifiez l'ordre de priorité de chargement des variables d'environnement ; les valeurs de la plateforme de déploiement peuvent écraser le fichier local .env.
4. Vérifiez si la clé a été révoquée, ainsi que l'organisation et le projet auxquels elle appartient. Si vous avez défini explicitement des en-têtes d'organisation ou de projet, assurez-vous qu'ils correspondent ; n'ajoutez pas d'en-têtes à l'aveugle.
5. Rechargez l'environnement d'exécution puis lancez une vérification en lecture seule. Si l'erreur persiste, notez l'ID de requête de la réponse et contactez le responsable du compte.

Vérification locale sans afficher les identifiants

import os

name = "OPENAI_API_KEY"
key = os.environ.get(name, "")
print({
    "variable": name,
    "present": bool(key),
    "length": len(key),
    "has_whitespace": any(c.isspace() for c in key),
    "wrapped_in_quotes": len(key) >= 2 and key[0] == key[-1] and key[0] in (chr(34), chr(39)),
})

N'utilisez pas de journaux de débogage qui affichent les en-têtes complets, et ne collez pas la clé convertie en hexadécimal dans un ticket ; il s'agit toujours de l'identifiant complet.

Requête de validation en lecture seule

Exécutez le code suivant dans l'environnement du serveur. Il lit la liste des modèles et ne soumet aucune génération de contenu. Une clé restreinte peut tout de même être rejetée faute d'autorisation de lecture ; ne concluez pas qu'une clé est corrompue à partir de n'importe quelle réponse non 200.

import os
import re
import requests

key = os.environ.get("OPENAI_API_KEY", "")
if not key or any(ord(c) < 33 or ord(c) > 126 for c in key) or any(c in key for c in (chr(34), chr(39))):
    raise SystemExit("Check the key environment variable: empty, whitespace, control characters, or quotes")
try:
    response = requests.get(
        "https://api.openai.com/v1/models",
        headers={"Authorization": f"Bearer {key}"},
        timeout=30,
    )
except requests.RequestException as exc:
    raise SystemExit("Request failed: " + type(exc).__name__) from None
print("HTTP", response.status_code)
if response.ok:
    print("Model list received")
else:
    try:
        body = response.json()
        error = body.get("error", {})
        message = str(error.get("message") or body.get("message") or "")
        message = message.replace(key, "[REDACTED]")
        message = re.sub(r"sk-[A-Za-z0-9_*.-]+", "[REDACTED]", message)
        print("code:", error.get("code") or body.get("error_code"))
        print("type:", error.get("type"))
        print("message:", message)
        print("request_id:", error.get("request_id") or response.headers.get("x-request-id"))
    except ValueError:
        print("Non-JSON response; check the base URL and network path")

Que vérifier lors du passage à HiAPI

Avec HiAPI, remplacez la clé par HIAPI_API_KEY, utilisez l'adresse de HiAPI comme Base URL, puis choisissez le point d'entrée de requête selon la page du modèle. Lisez d'abord la documentation d'authentification HiAPI et le guide de choix des interfaces.

Les deux requêtes doivent utiliser indépendamment les identifiants de leur propre plateforme ; n'envoyez pas une clé OpenAI à HiAPI pour une prétendue « vérification d'isolation ».

Questions fréquentes

Un préfixe de clé correct garantit-il qu'elle est utilisable ?

Le préfixe seul ne suffit pas. Vérifiez aussi la valeur complète, l'état de révocation et la configuration du compte.

Faut-il recharger immédiatement le compte en cas de 401 ?

Traitez d'abord la cause d'authentification indiquée par la réponse ; les erreurs de solde ou de limite d'utilisation se traitent séparément selon le code d'erreur correspondant.

Faut-il ajouter des en-têtes d'organisation et de projet à toutes les requêtes ?

Ne les ajoutez pas à l'aveugle. Les cas multi-organisations ou de clés utilisateur anciennes exigent un choix de contexte correct ; les en-têtes déjà définis doivent correspondre aux identifiants utilisés.

Une clé HiAPI peut-elle servir directement à appeler OpenAI ?

Non, elles ne sont pas interchangeables. HiAPI et OpenAI gèrent chacun leurs identifiants ; le domaine et la clé doivent correspondre.

Poursuivre le dépannage des erreurs de clé HiAPI.