Clave de API de OpenAI no válida: 401, variables de entorno y solución de problemas de configuración del proyecto

TL;DR

Cuando OpenAI devuelve 401 e indica que la clave es incorrecta, primero revisa las credenciales, las variables en tiempo de ejecución y la configuración de la organización o del proyecto. Para el 429, comprueba según el código de error la tasa, el saldo o el límite de uso; para el 403 también es necesario leer el motivo concreto.

Antes de ejecutar el ejemplo de Python, ejecuta python -m pip install requests en el mismo entorno de Python.

Primero distingue el tipo de error

Respuesta	Dirección de comprobación
401, mensaje Incorrect API key	Clave completa, ortografía, estado de revocación y pertenencia
401, otros mensajes de autenticación	Pertenencia a la organización, permisos o restricciones de IP, entre otros motivos concretos
403	Lee el motivo de la respuesta, incluidas restricciones regionales u otras restricciones de acceso
429	Distingue entre limitación de tasa, saldo y límite de uso de la organización o del proyecto

No juzgues que una clave es válida solo por el prefijo sk-. Las credenciales completas, el dominio de destino y la configuración de la cuenta deben coincidir.

Comprobación del entorno de ejecución en cinco pasos

1. Confirma si llamas a OpenAI o a una plataforma compatible; cada plataforma usa su propia clave.
2. Revisa la OPENAI_API_KEY del proceso real y descarta valores vacíos, marcadores de posición y copias erróneas.
3. Comprueba la prioridad de carga de las variables de entorno; los valores de la plataforma de despliegue pueden sobrescribir el .env local.
4. Verifica si la clave ha sido revocada y a qué organización y proyecto pertenece. Si has establecido manualmente encabezados de organización o proyecto, confirma que estos valores coinciden; no añadas encabezados a ciegas.
5. Tras recargar el entorno de ejecución, realiza una comprobación de solo lectura. Si el error persiste, registra el request ID de la respuesta y contacta con el responsable de la cuenta.

Comprobación local sin exponer credenciales

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)),
})

No uses registros de depuración que impriman encabezados de solicitud completos ni pegues en un ticket la clave convertida a hexadecimal; sigue siendo una credencial completa.

Solicitud de verificación de solo lectura

Ejecuta el siguiente código en el entorno del servidor. Lee la lista de modelos y no envía contenido generado. Es posible que una clave restringida siga siendo rechazada por falta de permisos de lectura; no se debe considerar que cualquier respuesta distinta de 200 implica que la clave esté dañada.

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")

Qué comprobar al cambiar a HiAPI

Al usar HiAPI, cambia la clave a HIAPI_API_KEY, usa la dirección de HiAPI como Base URL y luego elige el punto de entrada de la solicitud según la página del modelo. Lee primero la descripción de autenticación de HiAPI y la guía de selección de interfaz.

Las dos solicitudes deben usar de forma independiente las credenciales de cada plataforma; no envíes la clave de OpenAI a HiAPI para una supuesta "verificación aislada".

Preguntas frecuentes

¿Si el prefijo de la clave es correcto, significa que es utilizable?

No se puede determinar solo por el prefijo. También hay que comprobar el valor completo, el estado de revocación y la configuración de la cuenta.

¿Debo recargar inmediatamente al recibir un 401?

Primero aborda el motivo de autenticación indicado en la respuesta; los errores de saldo o de límite de uso deben tratarse por separado según el código de error correspondiente.

¿Todas las solicitudes deben incluir los encabezados de organización y proyecto?

No los añadas a ciegas. En casos como múltiples organizaciones o claves de usuario heredadas hay que seleccionar correctamente el contexto; los encabezados ya establecidos deben coincidir con las credenciales utilizadas.

¿Se puede usar una clave de HiAPI para solicitar directamente a OpenAI?

No son intercambiables. HiAPI y OpenAI gestionan sus credenciales por separado; el dominio y la clave deben corresponderse.

Continúa solucionando los errores de claves de HiAPI.