Cómo obtener una clave de API de OpenAI y solucionar un error 401 «Clave de API no válida»

Un error 401 de OpenAI es un problema de autenticación, pero no siempre significa lo mismo. La solución más rápida es identificar el nombre de host de la solicitud, confirmar qué secreto cargó realmente el proceso en ejecución y, después, usar el cuerpo del error para distinguir entre una clave incorrecta, una clave revocada, una discrepancia de credenciales de una puerta de enlace o un bloqueo por lista de permitidos de IP.

Si está buscando cómo obtener una clave de API de OpenAI porque una solicitud acaba de fallar, no pegue a ciegas un secreto nuevo en la misma configuración. Primero determine si la solicitud va a api.openai.com o a una puerta de enlace compatible con OpenAI. Estos dos endpoints pueden requerir credenciales diferentes.

Nunca pegue una clave de API completa en un ticket, chat, captura de pantalla, registro ni en esta lista de comprobación. En su lugar, compare una huella digital derivada de forma segura o el sufijo enmascarado que muestra su proveedor.

¿Qué significa «clave de API no válida»?

Significa que el servicio que recibió la solicitud no pudo autenticar la credencial presentada para esa solicitud. Para una solicitud directa a OpenAI, el error oficial puede indicar Incorrect API key provided. Las primeras comprobaciones de OpenAI consisten en comparar la clave enmascarada del error con la clave prevista, asegurarse de que una aplicación no esté alternando entre dos claves y confirmar la configuración correcta de la organización cuando sea necesaria. La guía de OpenAI sobre claves incorrectas es la fuente de referencia para ese mensaje exacto.

El estado HTTP por sí solo no basta para diagnosticar la causa. Por ejemplo, OpenAI documenta que una solicitud bloqueada por una lista de permitidos de IP devuelve HTTP 401 con el tipo de error ip_not_authorized, incluso con una clave válida. Lea el cuerpo del error antes de rotar nada. La guía de OpenAI sobre listas de permitidos de IP explica la diferencia.

La lista de comprobación de diagnóstico de cinco minutos

Realice estas comprobaciones en orden. Deténgase cuando la evidencia apunte a una causa; cambiar varias cosas a la vez dificulta demostrar que una solución funciona.

1. Confirme el endpoint antes de tocar la clave

Esta es la comprobación más importante cuando un SDK tiene una base_url configurable.

• Una solicitud a https://api.openai.com/... necesita una credencial de API de OpenAI.
• Una solicitud a una puerta de enlace o proxy necesita la credencial y el formato de autenticación que documente esa puerta de enlace.
• Una solicitud puede parecer «compatible con OpenAI» en el código y, aun así, enviarse a un host que no es de OpenAI.

Cómo obtener una clave de API de OpenAI solo es relevante después de confirmar que la solicitud realmente va a OpenAI. Si el host es una puerta de enlace, crear una clave nueva de OpenAI no solucionará un error 401 de esa puerta de enlace. Compare el nombre de host configurado, la URL base del SDK, las variables de despliegue y cualquier configuración de proxy; no registre encabezados Authorization mientras lo hace.

Para una configuración de enrutamiento multimodelo, mantenga juntas la configuración del endpoint y de la clave. La guía más amplia de solución de problemas de API compatibles con OpenAI cubre URL base, nombres de modelos, streaming y comprobaciones específicas de enrutamiento después de que esta prueba directa de credenciales se supere.

2. Verifique que la aplicación esté cargando un único secreto previsto

Las causas comunes de un error de «clave de API no válida» son errores de configuración cotidianos:

• OPENAI_API_KEY no está configurada en el proceso en ejecución, aunque exista en su portátil.
• Un despliegue sigue haciendo referencia a una versión anterior del secreto.
• Un archivo .env no se está cargando en el entorno que realmente realiza la solicitud.
• El valor incluye comillas, espacios en blanco, un salto de línea o un marcador de posición copiado no intencionados.
• Una ruta de código usa un valor predeterminado de la biblioteca mientras otra sobrescribe la clave o la URL base.

Use una huella digital no reversible en un entorno privado de depuración. Esto le permite comparar qué secreto cargaron distintos procesos sin imprimir el secreto en sí:

import crypto from "node:crypto";

const key = process.env.OPENAI_API_KEY?.trim();

if (!key) {
  throw new Error("OPENAI_API_KEY is not set in this process");
}

const fingerprint = crypto
  .createHash("sha256")
  .update(key)
  .digest("hex")
  .slice(0, 12);

console.info({ keyConfigured: true, keyLength: key.length, fingerprint });

Compare la huella digital entre el desarrollo local, CI, staging, workers y producción. No compare ni almacene la clave completa.

3. Pruebe una solicitud directa con el mismo entorno de ejecución

Ejecute una solicitud mínima desde la misma máquina, contenedor o tarea que está fallando. Esto separa la carga de credenciales de la lógica de la aplicación. El siguiente comando utiliza el encabezado bearer estándar, pero deja deliberadamente la clave en una variable de entorno:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Interprete el resultado cuidadosamente:

• El mismo error 401 desde el mismo entorno de ejecución apunta a la credencial, el endpoint, la configuración de organización/proyecto o la política de red.
• Una respuesta correcta apunta a la configuración de la aplicación: un entorno de ejecución distinto, una anulación de la URL base, creación duplicada del cliente o una variable de entorno diferente.
• Una respuesta ip_not_authorized es un problema de inclusión de IP en listas permitidas, no evidencia de que el texto de la clave sea inválido.

No sustituya esta prueba por una solicitud desde el navegador. OpenAI aconseja no implementar claves de API en navegadores ni aplicaciones móviles porque pueden quedar expuestas y ser utilizadas por otras personas. Envíe las solicitudes a través de su propio backend. La guía de OpenAI sobre la seguridad de las claves de API explica el motivo.

4. Compruebe si la clave fue revocada, eliminada, expuesta o caducó

Los secretos de la API de OpenAI solo se muestran por completo en el momento de su creación. Si no guardó el secreto, no puede recuperarlo desde el panel; cree uno nuevo y actualice la aplicación. Las claves eliminadas no se pueden utilizar. El artículo de OpenAI sobre gestión de claves confirma ambos comportamientos.

Si está configurando una nueva integración en lugar de recuperarse de un incidente, use la guía de producción de claves de API de OpenAI complementaria para obtener una lista de verificación más amplia sobre configuración, seguridad y operación.

Trate estos eventos como un motivo para rotar la clave, no para reintentar indefinidamente:

• La clave fue eliminada o revocada intencionalmente.
• La clave puede haberse confirmado en un repositorio, enviado en un mensaje, incorporado en una aplicación cliente o expuesto de otro modo. OpenAI indica que deshabilita las claves que detecta en la internet pública o filtradas dentro de una aplicación de una tienda de apps.
• Se creó una clave de proyecto con una fecha de vencimiento y esa fecha ya pasó.
• Una implementación hace referencia a una clave anterior tras una rotación planificada.

Para sustituirla, cree la nueva clave en el proyecto previsto, escríbala en el almacén de secretos correcto, impleméntela, confirme una solicitud mínima y luego revoque la clave antigua. OpenAI recomienda fechas de vencimiento y un proceso de rotación regular; también recomienda claves separadas en lugar de credenciales compartidas por el equipo. Consulte las recomendaciones de seguridad actuales.

5. Compruebe la pertenencia al proyecto y los permisos de la clave

Si puede crear o ver una clave, pero una carga de trabajo del equipo sigue fallando, compruebe el límite del proyecto antes de asumir que el secreto está mal formado. Los proyectos de OpenAI administran claves de API, miembros, cuentas de servicio, acceso a modelos y límites de gasto. Las claves propiedad de usuarios se pueden configurar con permisos completos, restringidos o de solo lectura. La guía de proyectos de OpenAI documenta los controles disponibles.

Haga estas preguntas:

1. ¿La clave pertenece al mismo proyecto que los recursos de la aplicación y el uso previsto?
2. ¿La cuenta de servicio o el usuario sigue siendo miembro de ese proyecto?
3. ¿La clave tiene los permisos de endpoint/recurso que necesita la llamada?
4. Si el error identifica una organización, ¿el cliente está configurado para la organización prevista en lugar de una obsoleta?

Los problemas de permisos y de proyecto pueden tener un mensaje más específico o un código de estado diferente de Incorrect API key provided. Conserve el ID de solicitud del error y el cuerpo saneado para el responsable de su plataforma o el soporte de OpenAI, en lugar de hacer suposiciones.

6. Descarte la inclusión de IP en listas permitidas antes de rotar una clave válida

Una organización de OpenAI puede restringir el tráfico de la API a rangos de IP aprobados. Una solicitud desde cualquier otra dirección se rechaza con HTTP 401 y ip_not_authorized, incluso cuando la propia credencial es válida. Esto hace que sea un error 401 especialmente fácil de diagnosticar incorrectamente.

Si el tipo de error es ip_not_authorized:

1. Identifique la IP de salida real de la carga de trabajo, no la IP pública de la laptop del desarrollador.
2. Compárela con la lista de permitidos configurada y compruebe si cambió una NAT en la nube, una dirección de salida serverless o un proxy.
3. Actualice el rango permitido mediante los controles de organización adecuados.
4. Espere el período de propagación documentado antes de ejecutar de nuevo la prueba mínima.

Mantenga la clave sin cambios hasta descartar esta posibilidad. Rotar una clave válida solo añade una segunda variable al incidente.

Cómo obtener una clave de API de OpenAI después de un error 401

Si las pruebas muestran que la credencial falta, se eliminó, se vio comprometida o caducó, siga este breve flujo de recuperación:

1. Abra la página de claves de API de OpenAI en la organización y el proyecto previstos.
2. Cree una nueva clave secreta con el menor acceso adecuado para la carga de trabajo.
3. Guárdela directamente en un gestor de secretos del lado del servidor o en un secreto de implementación; no la incluya en código de navegador, en un archivo .env confirmado en el control de versiones ni en un documento compartido.
4. Actualice primero un entorno y ejecute la solicitud directa mínima.
5. Implemente el cambio en los entornos restantes y confirme que la huella digital cambió donde se esperaba.
6. Revocar la clave anterior solo después de verificar el reemplazo, a menos que la clave antigua esté expuesta; en ese caso, revóquela inmediatamente e investigue el uso.

Así se obtiene una clave de API de OpenAI de forma segura para una recuperación. No es motivo para compartir una misma clave entre compañeros de equipo o entornos. Use credenciales independientes de proyecto/usuario o de cuenta de servicio para que un futuro error 401 tenga un radio de impacto menor.

Un error 401 específico de una puerta de enlace requiere una pregunta distinta

Cuando una base de código utiliza un SDK compatible con OpenAI con una base_url personalizada, comience por: ¿Qué servicio recibió la solicitud? Una puerta de enlace puede devolver su propio error 401 antes de enviar nada a OpenAI. En ese caso, valide la credencial de la puerta de enlace, el tenant/espacio de trabajo, la URL base de la API y el identificador de modelo en la documentación de la propia puerta de enlace.

Una vez autenticada la solicitud, use la guía de inicio rápido de la API de Flatkey para una configuración centrada de un enrutador compatible, o vuelva a la guía de solución de problemas de la API compatible con OpenAI para comprobar el modelo, el streaming y la URL base. Mantenga una clave directa de OpenAI y una clave de puerta de enlace en variables de secreto con nombres independientes, para que un futuro incidente sea evidente a partir de la configuración y no mediante prueba y error.

Antes de cerrar el incidente

• [ ] El nombre de host y la base_url coinciden con el emisor de la credencial.
• [ ] El proceso de producción cargó la huella digital de secreto esperada.
• [ ] La clave no se ha eliminado, revocado, expuesto ni caducado.
• [ ] La pertenencia al proyecto y los permisos de la clave son correctos para la carga de trabajo.
• [ ] Se ha descartado ip_not_authorized o se actualizó la lista de permitidos.
• [ ] Una solicitud mínima funciona desde el entorno de ejecución que fallaba.
• [ ] No apareció ninguna credencial completa en registros, control de versiones, tickets o chat.
• [ ] La clave antigua se revocó solo después de verificar el reemplazo, a menos que estuviera expuesta.

Obtener una clave de API de OpenAI es una tarea de configuración útil; diagnosticar el host, el origen del secreto, el ciclo de vida y la política de red es lo que convierte una solución para un error 401 en una reparación duradera para producción.

Preguntas frecuentes

¿Qué significa una clave de API no válida en OpenAI?

Significa que el servicio que gestiona la solicitud no pudo autenticar la credencial presentada. Para el mensaje exacto Incorrect API key provided, compare la clave prevista con el valor enmascarado del error, asegúrese de que la aplicación no esté usando dos claves y compruebe la configuración de organización correcta. Un tipo de error diferente, como ip_not_authorized, indica otra causa.

¿Cómo obtengo una clave de API de OpenAI si la anterior ya no funciona?

Cree una nueva clave secreta en el proyecto de OpenAI previsto, guárdela en un almacén de secretos del lado del servidor, actualice la implementación activa y verifique una solicitud mínima antes de revocar la clave antigua. No puede recuperar el valor completo de una clave existente después de que desaparezca la pantalla de creación.

¿Puedo solucionar un error 401 de OpenAI poniendo una clave nueva en JavaScript del navegador?

No. Un navegador o una aplicación móvil no es el lugar adecuado para un secreto de proveedor. Envíe las solicitudes a través de su backend y almacene el secreto en la configuración del lado del servidor o en un gestor de secretos.

¿Por qué una clave válida de OpenAI devuelve 401 ip_not_authorized?

La lista de permitidos de IP de OpenAI puede rechazar solicitudes procedentes de una dirección que no está en la lista de permitidos de la organización. Compruebe la IP de salida real del servidor o de la carga de trabajo en la nube y compárela con los rangos de IP configurados.

¿Por qué una nueva clave de OpenAI no solucionó un error 401 de la puerta de enlace?

Un endpoint de puerta de enlace puede requerir su propia clave de API y configuración. Confirme el nombre de host de la solicitud y use la credencial emitida por el operador de ese endpoint; una clave directa de OpenAI no autentica una solicitud a todas las API compatibles con OpenAI.

Fuentes oficiales

• OpenAI: Se proporcionó una clave de API incorrecta
• OpenAI: Prácticas recomendadas para la seguridad de las claves de API
• OpenAI: Gestión de proyectos en la plataforma de API
• OpenAI: Lista de permitidos de IP para la API de OpenAI
• OpenAI: ¿Dónde encuentro mi clave de API de OpenAI?