Solução de Problemas de API Compatível com OpenAI: Corrija 401s, Nomes de Modelos, Streaming e URLs Base

A solução de problemas de uma API compatível com OpenAI fica muito mais fácil quando você para de tratar toda solicitação com falha como "o provedor está fora do ar". A maioria das migrações malsucedidas vem de uma de seis camadas: a chave, a URL base, a família de endpoint, o nome do modelo, o comportamento de streaming ou cobrança/retorno de leitura.

A Flatkey ajuda equipes a manter acesso a modelos, roteamento, cobrança, analytics de uso e controles operacionais em um só lugar, mas um cliente compatível com OpenAI ainda precisa de configuração precisa. Uma solicitação pode parecer correta no SDK e ainda assim falhar porque o cliente está apontando para a raiz /v1 errada, o alias do modelo pertence a uma família de endpoint diferente, ou o stream está sendo armazenado em buffer por um proxy.

Use este guia de solução de problemas de API compatível com OpenAI como um caminho de depuração limpo antes de alterar o código da aplicação. Comece com curl, prove uma solicitação sem streaming, adicione o SDK e, depois, adicione streaming, ferramentas e tráfego de produção uma camada por vez.

O caminho de cinco minutos para solução de problemas de API compatível com OpenAI

Antes de inspecionar o código do framework, capture a menor solicitação que deve funcionar. Para a Flatkey, use a URL base mostrada no seu console atual. A página inicial pública da Flatkey mostra atualmente uma solicitação para https://router.flatkey.ai/v1/chat/completions, o que significa que clientes SDK normalmente devem receber a raiz /v1 como URL base e o SDK deve acrescentar /chat/completions.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Responda exatamente: ok"}
    ]
  }'

Se essa solicitação falhar, o problema não é o framework da sua aplicação. Corrija primeiro a chave, a URL base, a família de endpoint ou o alias do modelo. Se funcionar, copie os mesmos valores para o SDK e continue depurando a partir daí.

A regra mais rápida de solução de problemas de uma API compatível com OpenAI é simples: não teste streaming, ferramentas, modo JSON, retries ou um fluxo completo de agente até que uma solicitação de texto simples sem streaming funcione.

Leia o erro como uma camada, não como um veredicto

Use o código de status para decidir o que alterar em seguida.

Sintoma	Camada provável	O que verificar primeiro
401, invalid_api_key ou erro de autenticação	Chave e cabeçalho de autenticação	Formato Bearer, origem da chave, espaços em branco copiados, chave do provedor versus chave do gateway
403 ou permissão negada	Conta, projeto ou política	Allowlist de IP, participação no projeto, aprovação do modelo, permissão do endpoint
404, model_not_found ou modelo desconhecido	Catálogo de modelos e família de endpoint	Alias exato do modelo, estado de ativação do modelo, /chat/completions versus /responses versus outro endpoint
400 solicitação malformada	Formato do payload	Campos obrigatórios, parâmetros sem suporte, schema de tool, formato da mensagem
O stream conecta, mas não aparecem tokens	Caminho de streaming	stream: true, parser SSE, proxy com buffering, suporte de streaming do endpoint
A solicitação funciona, mas o uso está ausente	Retorno de leitura e cobrança	Solicitação de comparação sem streaming, registro no dashboard, comportamento do evento final do stream
429, 500, 502, 503 ou 504	Taxa, capacidade ou upstream	Backoff, volume de solicitações, página de status, política de retry, rota de fallback

O próprio guia de erros da OpenAI trata 401s como problemas de autenticação, 429s como problemas de taxa ou cota, e respostas 500/503 como condições de servidor ou sobrecarga que podem ser tentadas novamente. Um gateway compatível com OpenAI pode adicionar seus próprios detalhes, então preserve o corpo da resposta e o ID da solicitação quando for escalar o problema.

Corrija 401s antes de trocar modelos

Um 401 é o desvio mais comum na solução de problemas de API compatível com OpenAI porque parece um problema de modelo ou rota quando, normalmente, é um problema de autenticação.

Verifique estes itens nesta ordem:

1. A solicitação tem exatamente um cabeçalho Authorization: Bearer ....
2. A chave é uma chave da Flatkey ao chamar a Flatkey, e não uma chave direta da OpenAI, Anthropic, Google ou uma chave de teste.
3. A chave não contém aspas copiadas, nova linha, prefixo invisível ou espaço no final.
4. A chave é carregada do ambiente em que seu processo realmente executa, e não apenas do seu shell.
5. A conta, o projeto, a equipe ou a política de IP permitem a rota.

Use uma verificação rápida no shell que não imprima a chave:

test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c

Se o curl funcionar, mas o SDK retornar 401, inspecione os nomes das variáveis de ambiente. O cliente Python da OpenAI lê OPENAI_API_KEY por padrão, e o cliente Node lê OPENAI_API_KEY por padrão. Se seu app ainda exporta OPENAI_API_KEY com uma chave antiga de provedor direto, o SDK pode ignorar sua nova chave de gateway, a menos que você passe api_key ou apiKey explicitamente.

Corrija a URL base sem duplicar o endpoint

Erros de URL base geralmente caem em dois padrões:

1. O SDK recebe o endpoint completo, como https://router.flatkey.ai/v1/chat/completions, e então acrescenta /chat/completions novamente.
2. O SDK recebe apenas o domínio, como https://router.flatkey.ai, e nunca alcança a rota /v1 compatível com OpenAI.

Para Python, passe base_url ou defina OPENAI_BASE_URL. O código-fonte oficial do cliente Python também recorre a https://api.openai.com/v1 quando nenhum URL base personalizado é fornecido.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Responda exatamente: ok"}],
)

print(response.choices[0].message.content)

Para Node, passe baseURL ou defina OPENAI_BASE_URL. O cliente oficial do Node documenta baseURL como a substituição para a raiz padrão da API da OpenAI.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Responda exatamente: ok" }],
});

console.log(response.choices[0]?.message?.content);

Se esta etapa de solução de problemas da API compatível com OpenAI ainda falhar, registre o URL base resolvido no início da execução do processo. Não registre a chave.

Separe os nomes dos modelos das famílias de endpoints

"Modelo não encontrado" pode significar que o alias está errado, mas também pode significar que o alias está sendo enviado para a família de endpoints errada. Um modelo que funciona para chat completions pode não estar exposto por meio de Responses, Messages, imagens, vídeo ou embeddings com a mesma estrutura de payload.

Execute esta lista de verificação antes de renomear modelos em produção:

Verificação	Por que isso importa
Confirme o alias exato do modelo no console atual do Flatkey	Aliases do gateway podem diferir dos nomes de marketing do provedor direto
Confirme a família de endpoint	/v1/chat/completions e /v1/responses têm estruturas de solicitação diferentes
Remova parâmetros opcionais	Uma opção sem suporte pode ocultar o verdadeiro problema do modelo
Tente uma solicitação curta sem streaming	Uma solicitação simples isola a rota da análise do stream
Registre o corpo com falha e o carimbo de data/hora	Suporte e revisão de auditoria precisam do modelo, rota e erro exatos

A documentação de modelos externos da OpenAI usa a mesma ideia para endpoints personalizados: forneça um URL de endpoint, especifique slugs de modelos e execute uma chamada de verificação. Trate a configuração do seu gateway da mesma forma. Mantenha um pequeno mapa de modelos aprovados no código em vez de deixar que cada serviço use strings brutas de modelo.

Depure streaming depois que o modo sem streaming funcionar

O streaming deve ser um teste de segunda etapa. A referência de Chat Completions da OpenAI retorna ou um objeto JSON de conclusão de chat ou uma sequência transmitida de objetos de fragmentos de conclusão de chat. A API Responses também oferece suporte a text/event-stream quando stream está habilitado.

Use uma verificação direta de stream:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Conte de um a cinco lentamente."}
    ]
  }'

Se a solicitação sem streaming funcionar e o stream não, inspecione o caminho do stream:

• Confirme que a resposta usa um tipo de conteúdo compatível com SSE.
• Desative o middleware do cliente de API que armazena toda a resposta em buffer antes de retorná-la.
• Desative o buffering do proxy reverso para esta rota.
• Verifique se o analisador do seu frontend espera fragmentos de Chat Completions enquanto sua rota retorna eventos de Responses.
• Compare com a lista de verificação de streaming existente do Flatkey em /blog/openai-compatible-streaming-sse-test.

Esta etapa de solução de problemas da API compatível com OpenAI é especialmente importante em ferramentas sem servidor e de automação. Alguns wrappers retornam um status HTTP bem-sucedido enquanto ocultam o fato de que nenhum token chegou ao chamador até o stream ser fechado.

Adicione ferramentas somente depois que a solicitação base estiver limpa

A chamada de ferramentas adiciona outra camada de falha. Um gateway, rota ou modelo selecionado pode aceitar mensagens simples de chat, mas rejeitar um esquema de ferramenta, tool_choice, chamadas paralelas de ferramentas ou configurações rígidas de saída estruturada.

Use uma escada de três solicitações:

1. Solicitação de texto simples com o mesmo modelo.
2. Mesma solicitação com um pequeno esquema de função.
3. Esquema completo de ferramentas de produção.

Se a solicitação 1 funcionar e a solicitação 2 falhar, você não está mais depurando autenticação ou URL base. Você está depurando capacidade do modelo, família de endpoint ou suporte ao esquema. Remova campos opcionais, encurte descrições e verifique se a rota do modelo selecionado oferece suporte ao comportamento de ferramenta de que você precisa.

Comprove o uso e a leitura de cobrança

Não encerre a solução de problemas de API compatível com OpenAI em "a resposta retornou texto". Para uma migração em produção, você também precisa comprovar que a solicitação é visível onde as equipes de finanças e operações irão revisá-la.

Após um teste inicial bem-sucedido, capture:

Evidência	O que ela comprova
Timestamp e rota da solicitação	Qual caminho do gateway recebeu tráfego
Alias do modelo	Qual modelo configurado foi solicitado
Status da resposta e ID da solicitação	O que o suporte pode rastrear
Objeto de uso ou contagem de tokens	Se o app consegue registrar os fatores de custo
Leitura do painel ou de faturamento	Se o financeiro consegue reconciliar os gastos
Evento de fallback ou retry, se houver	Se a política de roteamento alterou o caminho

A Flatkey está posicionada em torno de uma chave, preços claros, faturamento unificado e um painel para chaves, uso e roteamento. Para uma migração, combine o teste inicial de engenharia com uma verificação de leitura de uso no console antes de mover tráfego real.

Um fluxo de solução de problemas seguro para produção

Use esta sequência quando uma migração para uma API compatível com OpenAI estiver falhando:

1. Execute uma solicitação curl sem streaming com a URL base atual do console, uma chave e um alias de modelo aprovado.
2. Corrija qualquer 401 ou 403 antes de alterar os payloads.
3. Corrija a composição da URL base antes de alterar as versões do SDK.
4. Corrija o alias do modelo e a família do endpoint antes de alterar a política de retry.
5. Adicione o SDK com api_key ou apiKey explícito e base_url ou baseURL.
6. Adicione streaming e verifique se o cliente recebe eventos incrementais.
7. Adicione ferramentas ou saída estruturada uma funcionalidade por vez.
8. Verifique o uso e a leitura de faturamento.
9. Mova os valores que funcionam para uma configuração pronta para rollback.

Essa ordem evita que a solução de problemas de API compatível com OpenAI vire uma sessão de adivinhação. Cada etapa ou prova uma camada ou lhe dá uma falha menor para corrigir.

Quando a Flatkey ajuda

A Flatkey é útil quando o problema raiz é a complexidade operacional: muitas chaves de provedores, acesso inconsistente a modelos, uso difícil de revisar e caminhos de faturamento separados. Um gateway unificado não elimina a necessidade de testar família do endpoint, alias do modelo, streaming, ferramentas e leitura de faturamento, mas dá à equipe um único lugar para padronizar essas verificações.

Se você estiver migrando um app, combine este guia com o guia de migração compatível com OpenAI da Flatkey em /blog/openai-compatible-api-migration e a checklist de teste inicial em /blog/ai-api-smoke-test-checklist.

Quando estiver pronto para testar o fluxo com uma chave da Flatkey, comece em /sign-up e mantenha o primeiro teste inicial pequeno o suficiente para inspecionar manualmente.

Perguntas frequentes

Por que minha API compatível com OpenAI retorna 401 quando a chave está definida?

O processo pode estar lendo uma variável de ambiente diferente daquela que você alterou, ou a chave pode pertencer ao provedor errado. Verifique o nome da variável resolvida, o cabeçalho Authorization: Bearer, espaços em branco copiados e qualquer política de conta ou IP.

A URL base do SDK deve incluir /chat/completions?

Normalmente, não. Forneça ao SDK a URL base /v1 e deixe o SDK acrescentar o endpoint. Passar o endpoint completo costuma criar caminhos duplicados.

Por que um modelo funciona sem streaming, mas falha com stream: true?

A rota base pode estar correta enquanto o caminho de streaming é bloqueado por middleware de buffering, uma incompatibilidade do parser SSE ou uma combinação de rota/modelo que não oferece suporte a streaming. Teste com curl -N antes de depurar o código do frontend.

Por que "model not found" acontece com um nome de modelo válido?

O alias pode ser válido em uma família de endpoint e inválido em outra, ou o gateway pode expor um alias diferente do provedor direto. Confirme juntos o alias atual do console e a família do endpoint.

O que devo testar antes de enviar tráfego de produção?

Teste uma solicitação sem streaming, uma solicitação do SDK, um stream, uma chamada de ferramenta representativa se seu app usar ferramentas, um caminho de falha e um registro de faturamento/leitura de uso. Depois, mantenha uma configuração de rollback para a rota anterior do provedor.

A solução de problemas de API compatível com OpenAI não é sobre memorizar cada erro de cada provedor. É sobre comprovar o caminho da chave à URL base, da URL base à família do endpoint, da família do endpoint ao alias do modelo e da resposta bem-sucedida ao registro de uso. Quando essas camadas estão claras, alternar tráfego pela Flatkey se torna uma migração controlada, e não uma sessão de depuração madrugada adentro.