Um erro 401 da OpenAI é um problema de autenticação, mas nem sempre significa a mesma coisa. A correção mais rápida é identificar o nome do host da solicitação, confirmar qual segredo o processo em execução realmente carregou e, em seguida, usar o corpo do erro para distinguir uma chave incorreta de uma chave revogada, uma incompatibilidade de credenciais de gateway ou um bloqueio por lista de permissões de IP.
Se você está procurando como obter uma chave de API da OpenAI porque uma solicitação acabou de falhar, não cole cegamente um novo segredo na mesma configuração. Primeiro, determine se a solicitação está indo para api.openai.com ou para um gateway compatível com OpenAI. Esses dois endpoints podem exigir credenciais diferentes.
Nunca cole uma chave de API completa em um ticket, chat, captura de tela, log ou nesta lista de verificação. Em vez disso, compare uma impressão digital derivada de forma segura ou o sufixo mascarado exibido pelo seu provedor.
O que significa “chave de API inválida”?
Isso significa que o serviço que recebeu a solicitação não conseguiu autenticar a credencial apresentada para essa solicitação. Para uma solicitação direta à OpenAI, o erro oficial pode informar Incorrect API key provided. As primeiras verificações da OpenAI são comparar a chave mascarada no erro com a chave pretendida, garantir que um aplicativo não esteja alternando entre duas chaves e confirmar a configuração correta da organização quando ela for necessária. As orientações da OpenAI sobre chave incorreta são a fonte de referência para essa mensagem exata.
O status HTTP por si só não é suficiente para diagnosticar a causa. Por exemplo, a OpenAI documenta que uma solicitação bloqueada pela lista de permissões de IP retorna HTTP 401 com o tipo de erro ip_not_authorized — mesmo com uma chave válida. Leia o corpo do erro antes de fazer qualquer rotação. O guia de lista de permissões de IP da OpenAI explica a distinção.
A lista de verificação de diagnóstico de cinco minutos
Execute estas verificações em ordem. Pare quando as evidências apontarem para uma causa; alterar várias coisas de uma vez torna difícil comprovar uma correção que funciona.
| Verificação | O que inspecionar com segurança | Conclusão provável | Próxima ação |
|---|---|---|---|
| 1. Host da solicitação | O nome do host após redirecionamentos, por exemplo, api.openai.com em comparação com um domínio de gateway |
Uma chave direta da OpenAI foi enviada a outro provedor, ou vice-versa | Use a credencial emitida pelo operador do endpoint |
| 2. Corpo exato do erro | Mensagem de erro, type e code — nunca o segredo completo |
Chave incorreta/revogada, bloqueio de IP ou uma regra de autenticação específica do provedor | Siga abaixo a ramificação que corresponde ao corpo |
| 3. Fonte do segredo em tempo de execução | Ambiente do processo, referência ao segredo de implantação, nome do segredo de CI ou revisão do contêiner | Um valor antigo, vazio, truncado ou entre aspas ainda está em execução | Atualize a fonte de segredo ativa e reinicie/reimplante deliberadamente |
| 4. Ciclo de vida da chave | Se a chave foi excluída, revogada, exposta ou configurada para expirar | A chave original não consegue mais autenticar | Crie uma substituta e faça a rotação com segurança |
| 5. Projeto e permissões | Participação no projeto, projeto pretendido e permissões da chave | A chave existe, mas não tem o acesso de que a solicitação precisa | Use a chave do projeto pretendido ou peça a um proprietário para ajustar o acesso |
| 6. Controles de rede | IP de saída e configuração da lista de permissões de IP da OpenAI | ip_not_authorized ou uma alteração de IP da infraestrutura |
Atualize a lista de permissões; aguarde o tempo de propagação antes de testar novamente |
1. Confirme o endpoint antes de mexer na chave
Esta é a verificação mais importante quando um SDK tem uma base_url configurável.
- Uma solicitação para
https://api.openai.com/...precisa de uma credencial de API da OpenAI. - Uma solicitação para um gateway ou proxy precisa da credencial e do formato de autenticação documentados por esse gateway.
- Uma solicitação pode parecer “compatível com OpenAI” no código, mas ainda assim ser enviada para um host que não é da OpenAI.
Saber como obter uma chave de API da OpenAI só é relevante depois que você confirmar que a solicitação está realmente indo para a OpenAI. Se o host for um gateway, criar uma nova chave da OpenAI não corrigirá um erro 401 desse gateway. Compare o nome do host configurado, a URL base do SDK, as variáveis de implantação e qualquer configuração de proxy; não registre cabeçalhos Authorization durante esse processo.
Para uma configuração de roteamento multimodelo, mantenha a configuração do endpoint e da chave juntas. O guia mais amplo de solução de problemas de API compatível com OpenAI aborda URLs base, nomes de modelos, streaming e verificações específicas de roteamento depois que este teste direto de credenciais for aprovado.
2. Verifique se o aplicativo está carregando um único segredo pretendido
Causas comuns de um erro de “chave de API inválida” são erros comuns de configuração:
OPENAI_API_KEYnão está definido no processo em execução, embora exista no seu laptop.- Uma implantação ainda faz referência a uma versão mais antiga do segredo.
- Um arquivo
.envnão está sendo carregado no ambiente que realmente faz a solicitação. - O valor inclui aspas, espaços em branco, uma quebra de linha ou um marcador de posição copiado não intencionalmente.
- Um caminho de código usa um padrão da biblioteca, enquanto outro substitui a chave ou a URL base.
Use uma impressão digital não reversível em um ambiente privado de depuração. Isso permite comparar qual segredo diferentes processos carregaram sem imprimir o próprio segredo:
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 a impressão digital entre o desenvolvimento local, CI, staging, workers e produção. Não compare nem armazene a chave completa.
3. Teste uma solicitação direta com o mesmo ambiente de execução
Execute uma solicitação mínima na mesma máquina, contêiner ou tarefa que está falhando. Isso separa o carregamento de credenciais da lógica da aplicação. O comando a seguir usa o cabeçalho bearer padrão, mas deliberadamente mantém a chave em uma variável de ambiente:
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
Interprete o resultado com cuidado:
- O mesmo 401 no mesmo ambiente de execução indica um problema na credencial, no endpoint, na configuração de organização/projeto ou na política de rede.
- Uma resposta bem-sucedida indica a configuração da aplicação: um ambiente de execução diferente, uma substituição de URL base, criação duplicada de cliente ou uma variável de ambiente diferente.
- Uma resposta
ip_not_authorizedé um problema de lista de permissões de IP, não uma evidência de que o texto da chave seja inválido.
Não substitua este teste por uma solicitação do navegador. A OpenAI recomenda não implantar chaves de API em navegadores ou apps móveis, pois elas podem ser expostas e usadas por terceiros. Em vez disso, envie as solicitações pelo seu próprio backend. As orientações de segurança para chaves de API da OpenAI explicam o motivo.
4. Verifique se a chave foi revogada, excluída, exposta ou expirou
Os segredos da API da OpenAI só são exibidos integralmente no momento da criação. Se você não salvou o segredo, não poderá recuperá-lo no painel; crie um novo e atualize a aplicação. Chaves excluídas não podem ser usadas. O artigo da OpenAI sobre gerenciamento de chaves confirma ambos os comportamentos.
Se você estiver configurando uma nova integração em vez de se recuperar de um incidente, use o guia de produção complementar sobre chaves de API da OpenAI para uma lista de verificação mais ampla de configuração, segurança e operação.
Trate estes eventos como um motivo para fazer a rotação, não para tentar novamente indefinidamente:
- A chave foi excluída ou revogada intencionalmente.
- A chave pode ter sido enviada para um repositório, enviada em uma mensagem, incorporada em um app cliente ou exposta de outra forma. A OpenAI informa que desativa chaves que detecta na internet pública ou vazadas em um app de loja de aplicativos.
- Uma chave de projeto foi criada com uma data de expiração, e essa data já passou.
- Uma implantação faz referência a uma chave anterior após uma rotação planejada.
Para substituí-la, crie a nova chave no projeto pretendido, grave-a no armazenamento de segredos correto, faça a implantação, confirme uma solicitação mínima e então revogue a chave antiga. A OpenAI recomenda datas de expiração e um processo regular de rotação; também recomenda chaves separadas em vez de credenciais compartilhadas pela equipe. Veja as recomendações de segurança atuais.
5. Verifique a associação ao projeto e as permissões da chave
Se você consegue criar ou ver uma chave, mas uma carga de trabalho da equipe ainda falha, verifique o limite do projeto antes de presumir que o segredo está malformado. Os projetos da OpenAI gerenciam chaves de API, membros, contas de serviço, acesso a modelos e limites de gastos. As chaves pertencentes a usuários podem ser configuradas com permissões completas, restritas ou somente leitura. O guia de projetos da OpenAI documenta os controles disponíveis.
Faça estas perguntas:
- A chave é do mesmo projeto que os recursos da aplicação e o uso pretendido?
- A conta de serviço ou o usuário ainda é membro desse projeto?
- A chave tem as permissões de endpoint/recurso necessárias para a chamada?
- Se o erro identificar uma organização, o cliente está configurado para a organização pretendida, em vez de uma organização desatualizada?
Problemas de permissões e de projeto podem ter uma mensagem mais específica ou um código de status diferente de Incorrect API key provided. Preserve o ID da solicitação do erro e o corpo sanitizado para o responsável pela sua plataforma ou o Suporte da OpenAI, em vez de tentar adivinhar.
6. Descarte a lista de permissões de IP antes de fazer a rotação de uma chave válida
Uma organização da OpenAI pode restringir o tráfego da API a intervalos de IP aprovados. Uma solicitação de qualquer outro endereço é rejeitada com HTTP 401 e ip_not_authorized, mesmo quando a credencial em si é válida. Isso torna esse 401 particularmente fácil de diagnosticar incorretamente.
Se o tipo de erro for ip_not_authorized:
- Identifique o IP de saída real da carga de trabalho — não o IP público do laptop do desenvolvedor.
- Compare-o com a lista de permissões configurada e verifique se um NAT na nuvem, endereço de saída serverless ou proxy foi alterado.
- Atualize o intervalo permitido pelos controles apropriados da organização.
- Aguarde o período de propagação documentado antes de executar novamente o teste mínimo.
Mantenha a chave inalterada até que essa hipótese seja descartada. Fazer a rotação de uma chave válida apenas adiciona uma segunda variável ao incidente.
Como obter uma chave de API da OpenAI após um 401
Se as evidências ցույցarem que a credencial está ausente, foi excluída, comprometida ou expirou, siga este breve fluxo de recuperação:
- Abra a página de chaves de API da OpenAI na organização e no projeto pretendidos.
- Crie uma nova chave secreta com o menor nível de acesso adequado à carga de trabalho.
- Salve-a diretamente em um gerenciador de segredos do lado do servidor ou em um segredo de implantação; não a coloque em código de navegador, em um arquivo
.envversionado ou em um documento compartilhado. - Atualize primeiro um ambiente e execute a solicitação direta mínima.
- Implemente a alteração nos ambientes restantes e confirme que a impressão digital mudou onde esperado.
- Revogue a chave anterior somente depois que a substituição for verificada, a menos que a chave antiga esteja exposta — nesse caso, revogue-a imediatamente e investigue o uso.
É assim que se obtém uma chave de API da OpenAI com segurança para uma recuperação. Isso não é motivo para compartilhar uma única chave entre colegas de equipe ou ambientes. Use credenciais separadas de projeto/usuário ou conta de serviço para que um futuro erro 401 tenha um raio de impacto menor.
Um 401 específico de gateway exige uma pergunta diferente
Quando uma base de código usa um SDK compatível com OpenAI com um base_url personalizado, comece com: Qual serviço recebeu a solicitação? Um gateway pode retornar seu próprio 401 antes de enviar qualquer coisa upstream para a OpenAI. Nesse caso, valide a credencial do gateway, o tenant/espaço de trabalho, o URL base da API e o identificador do modelo na própria documentação do gateway.
Depois que a solicitação estiver autenticada, use o guia de início rápido da API Flatkey para uma configuração focada de roteador compatível, ou volte ao guia de solução de problemas da API compatível com OpenAI para verificações de modelo, streaming e URL base. Mantenha uma chave direta da OpenAI e uma chave de gateway em variáveis de segredo com nomes distintos, para que um incidente futuro seja evidente na configuração, em vez de depender de tentativa e erro.
Antes de encerrar o incidente
- [ ] O nome do host e o
base_urlcorrespondem ao emissor da credencial. - [ ] O processo de produção carregou a impressão digital do segredo esperada.
- [ ] A chave não foi excluída, revogada, exposta nem expirou.
- [ ] A associação ao projeto e as permissões da chave estão corretas para a carga de trabalho.
- [ ]
ip_not_authorizedfoi descartado ou a lista de permissões foi atualizada. - [ ] Uma solicitação mínima funciona a partir do ambiente de execução que falhava.
- [ ] Nenhuma credencial completa apareceu em logs, controle de versão, tickets ou chat.
- [ ] A chave antiga foi revogada somente depois que a substituição foi verificada, a menos que estivesse exposta.
Obter uma chave de API da OpenAI é uma tarefa útil de configuração; diagnosticar o host, a fonte do segredo, o ciclo de vida e a política de rede é o que transforma uma correção de 401 em um reparo duradouro de produção.
Perguntas frequentes
O que significa chave de API inválida na OpenAI?
Significa que o serviço que processa a solicitação não conseguiu autenticar a credencial apresentada. Para a mensagem exata Incorrect API key provided, compare a chave pretendida com o valor mascarado no erro, certifique-se de que o aplicativo não está usando duas chaves e verifique a configuração da organização correta. Um tipo de erro diferente, como ip_not_authorized, indica outra causa.
Como obtenho uma chave de API da OpenAI se a antiga não funciona mais?
Crie uma nova chave secreta no projeto OpenAI pretendido, salve-a em um armazenamento de segredos do lado do servidor, atualize a implantação ativa e verifique uma solicitação mínima antes de revogar a chave antiga. Você não pode recuperar o valor completo de uma chave existente depois que a tela de criação é fechada.
Posso corrigir um 401 da OpenAI colocando uma nova chave em JavaScript no navegador?
Não. Um navegador ou aplicativo móvel é o lugar errado para um segredo do provedor. Encaminhe as solicitações pelo seu backend e armazene o segredo na configuração do lado do servidor ou em um gerenciador de segredos.
Por que uma chave válida da OpenAI retorna 401 ip_not_authorized?
A lista de permissões de IP da OpenAI pode rejeitar solicitações de um endereço que não está na lista de permissões da organização. Verifique o IP de saída real do servidor ou da carga de trabalho na nuvem e, em seguida, compare-o com os intervalos de IP configurados.
Por que uma nova chave da OpenAI não corrigiu um 401 de gateway?
Um endpoint de gateway pode exigir sua própria chave de API e configuração. Confirme o nome do host da solicitação e use a credencial emitida pelo operador desse endpoint; uma chave direta da OpenAI não autentica uma solicitação para todas as APIs compatíveis com OpenAI.
