Chave de API da OpenAI inválida: diagnóstico de 401, variáveis de ambiente e configuração de projeto

TL;DR

Quando a OpenAI retorna 401 e indica que a chave está incorreta, verifique primeiro as credenciais, as variáveis em tempo de execução e a configuração da organização ou do projeto. Para 429, verifique a taxa, o saldo ou o limite de uso conforme o código de erro; para 403, também é necessário ler o motivo específico.

Antes de executar o exemplo em Python, execute python -m pip install requests no mesmo ambiente Python.

Primeiro, diferencie os tipos de erro

Resposta	Direção da verificação
401, com a mensagem Incorrect API key	Chave completa, grafia, status de revogação e titularidade
401, outras mensagens de autenticação	Motivos específicos como associação à organização, permissões ou restrições de IP
403	Ler o motivo da resposta, incluindo região ou outras restrições de acesso
429	Diferenciar limite de taxa, saldo e limite de uso da organização ou do projeto

Não julgue a chave como válida apenas pelo prefixo sk-. As credenciais completas, o domínio de destino e a configuração da conta precisam corresponder.

Cinco passos para verificar o ambiente de execução

1. Confirme se a chamada é para a OpenAI ou para uma plataforma compatível; cada plataforma usa sua própria chave.
2. Verifique o OPENAI_API_KEY do processo real, descartando valores vazios, placeholders e cópias incorretas.
3. Verifique a prioridade de carregamento das variáveis de ambiente; os valores da plataforma de implantação podem sobrescrever o .env local.
4. Confirme se a chave foi revogada e a qual organização e projeto pertence. Se você definiu explicitamente cabeçalhos de organização ou projeto, confirme que esses valores são consistentes; não adicione cabeçalhos às cegas.
5. Recarregue o ambiente de execução e faça uma verificação somente leitura. Se o erro persistir, registre o request ID da resposta e entre em contato com o responsável pela conta.

Verificação local sem expor credenciais

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ão use logs de depuração que imprimam cabeçalhos completos da requisição, nem converta a chave para hexadecimal e cole em um ticket; isso ainda é a credencial completa.

Requisição de verificação somente leitura

Execute o código a seguir no ambiente do servidor. Ele lê a lista de modelos e não envia conteúdo para geração. Chaves com restrições ainda podem ser rejeitadas por permissão de leitura insuficiente; não classifique qualquer resposta diferente de 200 como chave danificada.

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

O que verificar ao migrar para o HiAPI

Ao usar o HiAPI, troque a chave por HIAPI_API_KEY, use o endereço do HiAPI como Base URL e escolha o endpoint de requisição conforme a página do modelo. Leia primeiro a documentação de autenticação do HiAPI e o guia de seleção de endpoints.

As duas requisições devem usar de forma independente as credenciais de suas respectivas plataformas; não envie uma chave da OpenAI ao HiAPI para uma suposta “verificação isolada”.

Perguntas frequentes

Se o prefixo da chave estiver correto, ela é necessariamente válida?

Não é possível julgar apenas pelo prefixo. Verifique também o valor completo, o status de revogação e a configuração da conta.

Devo recarregar imediatamente ao encontrar um 401?

Trate primeiro o motivo de autenticação indicado pela resposta; erros de saldo ou limite de uso precisam ser tratados separadamente conforme o código de erro correspondente.

Todas as requisições precisam de cabeçalhos de organização e projeto?

Não adicione às cegas. Casos como múltiplas organizações ou chaves de usuário legadas exigem a seleção correta do contexto; os cabeçalhos já definidos devem corresponder às credenciais usadas.

Uma chave do HiAPI pode ser usada diretamente na OpenAI?

Não são intercambiáveis. O HiAPI e a OpenAI gerenciam suas próprias credenciais; o domínio e a chave precisam corresponder.

Continue diagnosticando erros de chave do HiAPI.