Nota do autor: se o curl funciona, mas o cliente retorna 401, 404, 400 ou não consegue se conectar, siga uma ordem fixa para verificar 7 pontos do serviço proxy de API. Inclui uma tabela de códigos de erro e um checklist de 10 minutos.
Com a mesma Key e o mesmo modelo, uma requisição via curl retorna 200, mas no Cherry Studio, Chatbox, Cursor, Cline, Claude Code ou Codex CLI aparece um erro 401, 404 ou 400 — ou simplesmente ocorre um timeout ou uma resposta vazia. Nesse caso, desconfie primeiro da configuração do cliente, antes de trocar a Key. Se o curl funciona, isso já mostra que a Key é válida e que a rede está acessível. O problema provavelmente está em alguma diferença entre a requisição que o cliente realmente envia e aquela que você imagina que ele envia.
A ordem recomendada de investigação é: Base URL → protocolo e endpoint → cabeçalho de autenticação → ID do modelo → corpo da requisição → rede. Antes disso, confirme se o cliente está realmente lendo a configuração que você alterou. Neste artigo, dividimos o caminho da requisição em 7 pontos de verificação, cada um com “sintoma, causa, como verificar e como corrigir”. O objetivo é ajudar você a descobrir em 10 minutos se o problema está no cliente, no gateway ou no serviço de origem.
Este não é mais um artigo explicando os conceitos básicos de APIs: é um manual de diagnóstico que você pode seguir na prática.
Por que o curl funciona, mas o cliente não conecta: pontos-chave para diagnosticar o proxy de API
O curl verifica apenas uma parte do caminho: resolução de DNS, handshake TLS, conectividade de rede, validade da chave e disponibilidade do endpoint que você testou manualmente. Ele não verifica se o cliente carregou a configuração alterada, como ele monta a Base URL ou se os cabeçalhos e o corpo da requisição enviada são iguais aos do curl.
Uma requisição que sai do cliente passa, aproximadamente, por esta cadeia: configuração do cliente (variáveis de ambiente, arquivo de configuração, interface gráfica) → montagem da Base URL → protocolo e endpoint → cabeçalho de autenticação → ID e mapeamento do modelo → corpo da requisição (mensagens, ferramentas, recursos multimodais, streaming) → proxy, TLS e rede → gateway → modelo de upstream. Se o curl funciona, isso só mostra que o caminho testado manualmente está funcionando. O cliente pode estar seguindo um caminho completamente diferente.
| Ponto de verificação | Sintoma típico | Como verificar primeiro |
|---|---|---|
| 1. Leitura da configuração | A alteração não surte efeito e o erro continua igual | Verifique a URL real da requisição nos logs do cliente |
| 2. Montagem da Base URL | Erro 404, /v1/v1 ou // no caminho |
Compare a URL dos logs com a URL do curl |
| 3. Protocolo e endpoint | Erro 404 ou 400, falha ao interpretar o formato da resposta | Confirme qual protocolo o cliente está usando |
| 4. Cabeçalho de autenticação | Erro 401, mas a chave funciona no curl | Compare as diferenças entre os cabeçalhos das requisições |
| 5. ID do modelo | Erro 404 ou 400 informando que o modelo não existe | Compare caractere por caractere com a lista de modelos do gateway |
| 6. Corpo da requisição | Texto puro funciona, mas adicionar imagem ou ferramenta causa erro 400 | Adicione variáveis gradualmente para reproduzir o problema |
| 7. Rede e streaming | Timeout, stream disconnected, resposta vazia | Desative o streaming para comparar e verifique o proxy |
Diagnóstico do serviço proxy de API, pontos 1 e 2: leitura da configuração e montagem da Base URL
Ponto 1: o cliente está lendo a configuração alterada?
Sintoma: você mudou a Base URL e a chave, mas o erro continua exatamente igual. Ou a configuração funciona em um projeto, mas não em outro.
Causa: a maioria dos clientes usa mais de uma fonte de configuração. Por exemplo: as configurações da interface gráfica podem sobrescrever as variáveis de ambiente; o arquivo de configuração pode ter vários perfis, e o perfil ativo não é aquele que você alterou; a configuração do projeto pode sobrescrever a global; ou um processo antigo ainda está em execução, usando os valores carregados na inicialização. Esse último caso é especialmente comum com ferramentas de linha de comando: você altera as variáveis de ambiente no terminal, mas o processo da IDE ou do agente que já está em execução não recebe os novos valores.
Como verificar: abra os logs ou a saída de depuração do cliente e confirme se a URL da requisição e os primeiros caracteres da chave correspondem aos valores que você acabou de configurar. Se for difícil consultar os logs, altere temporariamente a Base URL para um endereço claramente incorreto e veja se o erro muda. Assim, você consegue verificar se a configuração entrou em vigor.
Como corrigir: primeiro, descubra a ordem de prioridade das configurações do cliente. Em geral, as configurações da interface gráfica ou do projeto têm prioridade sobre o arquivo de configuração global, que por sua vez tem prioridade sobre as variáveis de ambiente. Mas as regras variam, então consulte a documentação do cliente. Depois, faça a alteração apenas na fonte de maior prioridade, remova os valores conflitantes das outras fontes e encerre completamente o processo do cliente antes de reiniciá-lo.
Ponto 2: barra final, /v1 duplicado e prefixo do caminho na Base URL
Sintoma: ocorre um erro 404 e a URL nos logs contém /v1/v1/chat/completions, //chat/completions ou termina em /v1/chat/completions/chat/completions.
Causa: cada cliente pode interpretar o campo Base URL de forma diferente. Alguns exigem o endereço raiz e acrescentam /v1 automaticamente; outros esperam um endereço que termine em /v1 e acrescentam /chat/completions; outros ainda têm campos separados para a Base URL e o endpoint completo. Se você preencher https://api.apiyi.com/v1/chat/completions em um campo que aceita apenas o prefixo, ou acrescentar uma barra ao endereço que já termina em /v1, o caminho montado pode ficar incorreto.
Como verificar: compare a URL completa da requisição nos logs, caractere por caractere, com a URL usada no curl. Veja principalmente quantas vezes /v1 aparece, se há barras duplas e se existem segmentos extras no final do caminho.
Como corrigir: preencha o campo conforme a documentação do cliente. Em clientes compatíveis com a OpenAI, normalmente se usa https://api.apiyi.com/v1, sem barra no final. Se o cliente acrescentar /v1 automaticamente, remova o /v1 inserido manualmente. Depois da alteração, confira novamente a URL nos logs e confirme se o caminho final segue o formato padrão, como https://api.apiyi.com/v1/chat/completions.
🎯 Sugestão de configuração: o endereço de acesso da APIYI (apiyi.com) compatível com a OpenAI é
https://api.apiyi.com/v1, no mesmo formato usado pelo SDK oficial da OpenAI. Você pode consultar os modelos disponíveis no console ou usar a mesma Base URL para acessar a interface de listagem de modelos. Use essa consulta para confirmar primeiro se a chave e o endereço estão corretos e, depois, ajuste o cliente.
Pontos de diagnóstico do proxy de API 3-4: endpoints de protocolo e cabeçalhos de autenticação
Ponto 3: o protocolo e o endpoint são compatíveis?
Sintoma: a Base URL parece correta, mas você ainda recebe um erro 404 ou 400. Ou a requisição é bem-sucedida, mas o cliente informa que não consegue interpretar a resposta ou retorna conteúdo vazio.
Causa: atualmente, as APIs mais usadas de Modelos de Linguagem Grande utilizam mais de um protocolo. Por exemplo, o cliente só aceita Chat Completions, mas você o direcionou para um endpoint que só oferece Responses. O Claude Code usa o protocolo Anthropic Messages, não o OpenAI Chat Completions. Já os caminhos e corpos de requisição do formato nativo do Gemini são completamente diferentes dos usados no formato compatível com OpenAI. No curl, você pode ter especificado o endpoint correto manualmente, enquanto o cliente faz a requisição usando seu próprio protocolo padrão.
| Tipo de protocolo | Caminho típico do endpoint | Clientes comuns | Autenticação |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Diversos clientes, como Cherry Studio, Chatbox e Cline | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
Ferramentas mais recentes do ecossistema OpenAI | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Ferramentas nativas da Anthropic, como Claude Code | x-api-key e anthropic-version |
| Gemini nativo | API nativa cujo caminho inclui o nome do modelo | SDK nativo do Gemini | Consulte a documentação oficial e a do gateway |
Como verificar: confira a parte final do caminho da requisição nos logs do cliente para identificar o protocolo usado. Depois, confirme se o endpoint do gateway escolhido oferece suporte a esse protocolo. Se o cliente tiver um menu de “tipo de provedor” ou “formato de API”, confira se a opção selecionada corresponde ao protocolo que você quer usar.
Como corrigir: alinhe o tipo de protocolo do cliente, a Base URL e o modelo. Para usar o formato compatível com OpenAI, selecione um provedor do tipo OpenAI. Ferramentas nativas como o Claude Code devem ser configuradas com o protocolo Anthropic. Quando precisar dos recursos nativos do Gemini, use o formato Gemini. A APIYI oferece suporte tanto ao formato compatível com OpenAI quanto aos formatos nativos de API do Claude, Gemini e outros. Consulte docs.apiyi.com para obter os endereços específicos de cada formato nativo, em vez de montar os caminhos de memória.
Ponto 4: os cabeçalhos de autenticação correspondem ao protocolo?
Sintoma: você recebe um erro 401, mas a mesma chave funciona normalmente no curl.
Causa: APIs compatíveis com OpenAI costumam usar Authorization: Bearer <Key>. A API nativa da Anthropic costuma usar x-api-key junto com anthropic-version. Algumas plataformas também exigem cabeçalhos relacionados à organização ou ao projeto. Você pode ter usado os cabeçalhos corretos no curl, mas o cliente pode ter enviado outros, seguindo um protocolo diferente, ou incluído um cabeçalho de organização que o gateway não reconhece, causando a falha de autenticação.
Como verificar: compare os cabeçalhos da requisição no curl e nos logs do cliente, prestando atenção aos campos Authorization, x-api-key, Content-Type e OpenAI-Beta. Verifique se há espaços, quebras de linha ou aspas extras antes ou depois da chave. Isso é comum ao copiar e colar de uma página da web.
Como corrigir: os cabeçalhos de autenticação devem seguir o protocolo. Ao selecionar o protocolo correto, a maioria dos clientes envia os cabeçalhos adequados automaticamente. Se o cliente permitir cabeçalhos personalizados, remova os de organização ou projeto que não forem necessários. Cole a chave novamente e confira se não há caracteres extras.
Diagnóstico de proxy de API, pontos 5 a 7: ID do modelo, corpo da requisição e streaming de rede
Ponto de verificação 5: ID e mapeamento do modelo
Sintoma: erro 404 ou 400 informando que o modelo não existe ou é inválido; ou apenas um modelo falha, enquanto os outros funcionam normalmente.
Causa: o ID do modelo precisa ser idêntico ao que aparece na lista de modelos do gateway. As diferenças mais comuns incluem letras maiúsculas e minúsculas, sufixos de versão, formato do prefixo (como provider/model) e aliases. O mesmo modelo pode ter nomes diferentes em plataformas distintas. Além disso, a lista integrada do cliente pode não incluir o ID desejado e substituí-lo silenciosamente pelo valor padrão.
Como verificar: copie o ID da interface de listagem de modelos do gateway ou do console e compare-o, caractere por caractere, com o campo model no corpo da requisição registrado nos logs do cliente. Se apenas um modelo falhar, verifique primeiro se o ID e o endpoint são compatíveis. Depois, confira se a conta tem permissão para usar esse modelo.
Como corrigir: adicione manualmente um modelo personalizado no cliente e cole o ID fornecido pelo gateway, sem digitá-lo. Se o cliente fizer o mapeamento de modelos, confirme se o nome resultante está correto.
💡 Dica sobre IDs de modelos: ao usar uma única chave para invocar modelos de diferentes provedores, como OpenAI, Claude, Gemini, DeepSeek e Qwen, pela APIYI apiyi.com, consulte a lista de modelos no console para obter o ID correto. O mesmo modelo pode ter nomes diferentes em cada plataforma; copiar o ID do console é a maneira mais simples de evitar problemas. Consulte também o console e a documentação para verificar a disponibilidade dos modelos.
Ponto de verificação 6: corpo da requisição e formato multimodal
Sintoma: conversas só com texto funcionam normalmente, mas enviar uma imagem, invocar uma ferramenta ou ativar parâmetros de raciocínio gera um erro 400.
Causa: os problemas de compatibilidade no corpo da requisição costumam estar nestes pontos: estrutura do array multimodal content; formato do campo image_url; imagens em base64 sem um prefixo MIME como data:image/png;base64,; campos de chamada de ferramentas incompatíveis com o protocolo atual; diferenças entre modelos no uso de max_tokens e max_completion_tokens; e parâmetros de raciocínio aceitos apenas por alguns modelos. Os parâmetros não são totalmente intercambiáveis entre fornecedores.
Como verificar: adicione uma variável de cada vez. Comece com uma requisição só de texto. Se funcionar, ative o streaming, depois adicione chamadas de ferramentas e, por fim, conteúdo multimodal. Teste a cada mudança: o campo adicionado na etapa em que a falha começar é o provável responsável. A mensagem de erro geralmente aponta o campo específico, então confira a resposta completa.
Como corrigir: desative os parâmetros avançados que não forem necessários no cliente e ajuste os campos conforme a documentação do modelo escolhido. Para imagens, use um prefixo base64 válido ou uma URL acessível. Defina as ferramentas no formato do protocolo atual.
Ponto de verificação 7: rede, proxy, TLS e buffer de streaming
Sintoma: tempo limite de conexão, stream disconnected, resposta vazia depois de uma longa espera ou funcionamento normal sem streaming, mas falha com streaming.
Causa: o cliente pode estar usando o proxy do sistema ou um proxy definido por variáveis de ambiente, enquanto o curl não usa, ou vice-versa. Firewall corporativo, validação de certificados TLS, resolução IPv6 e DNS também podem impedir a conexão do cliente. No streaming, alguns proxies armazenam a resposta em buffer e só a encaminham quando todo o conteúdo chega. Sem receber dados a tempo, o cliente interpreta isso como tempo limite ou interrupção do fluxo.
Como verificar: primeiro, diferencie uma conexão que não foi estabelecida de um fluxo interrompido. No primeiro caso, procure erros de TLS ou de conexão; no segundo, normalmente parte do conteúdo já foi recebida. Desative o streaming e tente novamente. Se a requisição funcionar sem streaming, o problema provavelmente está no buffer do proxy ou nas configurações de tempo limite. Verifique se as variáveis de ambiente de proxy são iguais no cliente e no terminal.
Como corrigir: alinhe as configurações de proxy do cliente e do curl; evite proxies que armazenam respostas em buffer nas requisições de streaming; e aumente, se necessário, o tempo limite do cliente. Para interrupções ocasionais no serviço de origem, faça um número limitado de novas tentativas ou mude temporariamente para outro modelo para verificar se o problema está em um único serviço de origem.
Introdução rápida ao serviço proxy de API: tabela de erros e checklist de configuração do cliente
Ao encontrar um erro, use primeiro o código para restringir as possíveis causas. Depois, confira cada item da lista de configuração.
Tabela de códigos de erro
| Código de erro | Causas comuns | O que verificar primeiro |
|---|---|---|
| 401 | Chave inválida, expirada ou desativada; formato incorreto do cabeçalho; organização ou projeto incompatível | Itens 1 e 4 |
| 403 | Chave válida, mas bloqueada por políticas do modelo, da organização ou da região; lista de permissões de IP; modelo não habilitado | Item 5 e permissões da conta |
| 404 | Caminho incorreto na Base URL; endpoint ou ID do modelo inexistente; rota não implementada pelo gateway | Itens 2, 3 e 5 |
| 400 | Corpo da requisição, parâmetros, ID do modelo ou campos multimodais inválidos; parâmetros incompatíveis com o fornecedor | Itens 5 e 6 |
| 429 | Limite de taxa ou cota insuficiente | Consulte Retry-After, aguarde antes de tentar novamente ou troque de modelo |
| 500/502/503/529 | Erro no provedor upstream ou no gateway; 529 costuma indicar sobrecarga | Faça um número limitado de tentativas e consulte os logs do gateway |
| Timeout, stream disconnected | Interrupção na rede, no proxy, no TLS ou no provedor upstream | Item 7 |
Checklist de configuração do cliente
| Item | O que confirmar |
|---|---|
| Origem da configuração | A alteração foi feita em uma variável de ambiente, arquivo de configuração ou interface gráfica? Qual tem prioridade? Há vários perfis ou configurações de projeto sobrescrevendo os valores? |
| Base URL | Inclui /v1? O cliente adiciona /v1 automaticamente? Há uma barra extra no final? |
| Tipo de endpoint | Chat Completions, Responses ou API nativa do Claude ou Gemini? A versão do cliente oferece suporte? |
| Cabeçalho de autenticação | Usa Authorization: Bearer ou x-api-key? É necessário incluir anthropic-version? |
| ID do modelo | Corresponde exatamente à lista de modelos do gateway, incluindo maiúsculas, minúsculas e prefixos? |
| Corpo da requisição | Inclui ferramentas, imagens ou parâmetros de reasoning? O campo max_tokens é compatível com o modelo escolhido? |
| Streaming e rede | O streaming está ativado? O proxy faz buffering? As configurações de proxy do cliente e do curl são iguais? |
Reproduza o problema com uma requisição mínima
O método mais eficaz é fazer uma comparação com as variáveis controladas: use a mesma Base URL, chave, modelo e corpo da requisição. Envie primeiro com curl e depois com o cliente. Siga estas etapas:
- Use o endpoint de lista de modelos para validar a chave e a Base URL, por exemplo, enviando uma requisição para
https://api.apiyi.com/v1/models; - Use uma requisição mínima de chat em texto puro para validar o endpoint e o ID do modelo;
- Ative o streaming para verificar a rede e o proxy;
- Acrescente chamadas de ferramentas ou conteúdo multimodal para validar o corpo da requisição;
- Em cada etapa, confira tanto os logs do cliente quanto os do gateway.
🚀 Dica de diagnóstico: no console da APIYI, você pode consultar estatísticas de uso e logs detalhados das chamadas. Se o cliente mostrar um erro, mas não houver nenhum registro da chamada no console, a requisição não chegou ao gateway: o problema está na configuração do cliente ou na rede local. Se houver um registro com informações de erro, use os logs para identificar se o problema está nos parâmetros ou no provedor upstream.
Perguntas frequentes (FAQ)
Q1: Se o curl funciona, mas o cliente não consegue se conectar, trocar a chave API ajuda?
Normalmente, não. Se o curl funciona, isso já indica que a chave API é válida. Quando parece que “trocar a chave resolveu”, muitas vezes é porque o cliente foi reiniciado ou o perfil foi alterado durante a troca, recarregando a configuração. Em vez de trocar a chave, feche o cliente completamente, reinicie-o e confira nos logs a Base URL e a chave API realmente usadas. Você também pode verificar o status e o histórico de chamadas dessa chave no console da APIYI para confirmar se há algum problema com ela.
Q2: Por que o endpoint /models funciona, mas a requisição de chat falha?
O endpoint de listagem de modelos verifica apenas se a autenticação e a Base URL estão basicamente corretas. Ele não envolve o endpoint de chat, o ID do modelo nem o corpo da requisição. Se o chat falhar, verifique nesta ordem: se o protocolo usado pelo cliente corresponde ao endpoint (ponto de verificação 3), se o ID do modelo é exatamente igual ao da lista (ponto de verificação 5) e se o corpo da requisição contém parâmetros que o modelo não suporta (ponto de verificação 6).
Q4: Se apenas um modelo falha e os outros funcionam, o que verificar primeiro?
Confira primeiro o ID do modelo e o endpoint; depois, as permissões da conta. Os erros mais comuns são diferenças entre maiúsculas e minúsculas, prefixos e aliases do ID do modelo. Outra possibilidade é que o modelo exija um protocolo diferente, como o formato nativo. Por último, verifique problemas de permissão ou disponibilidade. Com uma única chave API da APIYI, você pode alternar entre modelos de diferentes provedores. Testar temporariamente outro modelo semelhante ajuda a descobrir se o problema é específico de um modelo ou da configuração geral.
Q5: Como saber se o problema está no cliente ou no gateway?
O essencial é verificar duas coisas: se o gateway recebeu a requisição e se a mesma requisição funciona com curl. Se não há registro no gateway, o problema provavelmente está no cliente ou na rede local. Se a mesma requisição funciona com curl, mas falha no cliente, o problema provavelmente está na montagem da requisição ou no corpo dela. Se a requisição também falhar com curl e os logs mostrarem um erro 5xx, entre em contato com o suporte do gateway.
Resumo: checklist de 10 minutos para diagnosticar o serviço proxy de API e saber quando pedir ajuda
Se o curl funciona, mas o cliente não consegue se conectar, não troque a Key de imediato. Passe pelo checklist abaixo em 10 minutos:
- Confira os logs do cliente: obtenha a URL, os cabeçalhos e o corpo da requisição enviada e confirme que a configuração está em vigor;
- Confira a Base URL: confirme que
/v1aparece apenas uma vez e que não há barras duplas nem trechos de caminho duplicados; - Confira o protocolo do endpoint: Chat Completions, Responses, Claude Messages ou Gemini nativo devem ser compatíveis com o tipo de cliente;
- Confira o cabeçalho de autenticação:
Authorization: Beareroux-api-key. Remova cabeçalhos de organização desnecessários e espaços nas extremidades da Key; - Confira o ID do modelo: compare-o, caractere por caractere, com a lista de modelos do gateway;
- Envie uma requisição mínima: use a mesma Key, o mesmo modelo e o mesmo corpo para enviar uma requisição pelo curl e outra pelo cliente, depois compare os resultados;
- Adicione streaming: se falhar, verifique o buffering e os timeouts do proxy;
- Adicione ferramentas ou recursos multimodais: se falhar, verifique os campos do corpo da requisição;
- Faça o diagnóstico final: use os logs do gateway para decidir se o problema está no cliente ou no gateway.
Quando é um bug do cliente: não há registro da chamada no gateway, ou o curl funciona com exatamente a mesma URL, os mesmos cabeçalhos e o mesmo corpo, enquanto o cliente falha — e você já confirmou que a configuração está correta e que a versão é compatível com o endpoint. Nesse caso, atualize o cliente ou relate o problema ao projeto responsável por ele.
Quando procurar o suporte do gateway: a mesma requisição mínima também falha no curl, e os logs do gateway mostram a chamada com retorno 5xx; ou um modelo apresenta erros continuamente, enquanto outros funcionam, e você já descartou problemas de ID do modelo e de permissão. Ao entrar em contato com o suporte, envie o horário da requisição, o ID do modelo, o código de erro e a mensagem registrada nos logs. Isso acelera bastante o diagnóstico.
Para ferramentas de equipe que precisam de estabilidade, ter vários modelos e rotas já é uma forma de diagnosticar problemas: quando um deles apresenta falhas, basta mudar para outro e comparar os testes para identificar rapidamente o alcance do problema. Com uma única Key, o APIYI apiyi.com oferece acesso ao formato compatível com OpenAI e aos formatos nativos de Claude e Gemini. O uso e os logs no console ajudam na validação rápida; consulte o console e a documentação para preços e disponibilidade.
Autor: Equipe técnica da APIYI
Troca de ideias sobre tecnologia: entre em contato conosco pela página inicial do site APIYI
