|

Documentação de consulta do Request ID do APIYI atualizada e otimizada: duas formas de obter, pelo texto original do erro e pelos cabeçalhos de resposta

Documentação de consulta do Request ID do APIYI atualizada e otimizada: duas formas de obter, pelo texto original do erro e pelos cabeçalhos de resposta

Nota do autor: a documentação de consulta do Request ID da APIYI foi atualizada. Este artigo explica qual string copiar quando ocorre um erro, quais IDs não podem ser usados, como armazenar o task_id de vídeos assíncronos e quais materiais adicionar quando o log não encontra o registro.

Depois de um erro na chamada, ao abrir um ticket, desenvolvedores costumam travar no mesmo ponto: têm uma string de ID nas mãos, mas o suporte não a encontra no log. A causa normalmente é ter copiado o X-Request-Id do fornecedor upstream, em vez do X-Shellapi-Request-Id da própria APIYI. A nova documentação foi reescrita justamente para resolver esse problema; o endereço é docs.apiyi.com/faq/request-id-troubleshooting.

Não é apenas uma atualização cosmética da documentação. A versão antiga começava pelos “cabeçalhos de resposta” e estava cheia de “normalmente” e “talvez”; depois de ler, você ainda não sabia onde copiar. A nova versão inverteu a ordem: primeiro a resposta, depois como obter, e por fim o modelo de ticket.

Valor central: depois de ler este artigo, você consegue obter o Request ID correto em 10 segundos e também identificar quais IDs estão errados. Quando o log não tiver registro, você saberá quais materiais complementar.

apiyi-request-id-docs-upgrade-pt-pt-image-0


O que mudou na atualização da documentação de Request ID da APIYI

A primeira frase da nova documentação já entrega a resposta: o Request ID da APIYI é o X-Shellapi-Request-Id no cabeçalho de resposta, e, quando ocorre um erro, o final da mensagem de erro também traz o mesmo valor. Também foram corrigidas, de passagem, algumas expressões da página antiga que tratavam o x-request-id como “anote aí para facilitar a investigação”.

Item de informação Detalhes
Data de atualização 2026-11-16
Localização da documentação Nova página “Solução de problemas com Request ID” da seção FAQ
Resposta principal Request ID = cabeçalho de resposta X-Shellapi-Request-Id; o (request id: ...) no final da mensagem de erro é o mesmo valor
Conteúdo novo Duas formas de obtenção, tabela de correspondência de IDs, logs do console que não mostram o ID, explicação sobre vídeo assíncrono, o que fazer quando não encontrar e modelo de ticket
Observações de segurança O Request ID não é uma chave; pode ser colado em tickets, chats e capturas de tela. O que não pode ser divulgado externamente é a API Key completa que começa com sk-
Público afetado Todos os desenvolvedores que chamam, na APIYI, as interfaces de texto, imagem, Embedding, Claude Messages, Responses e vídeo assíncrono

Segundo o texto original da documentação, o nome desse cabeçalho de resposta não diferencia maiúsculas de minúsculas. Ele é retornado em requisições bem-sucedidas, erros de negócio e requisições de streaming; nestas últimas, o cabeçalho de resposta chega antes do primeiro bloco de dados. As interfaces de vídeo assíncrono também o retornam tanto no envio quanto na consulta.


Request ID da APIYI: qual sequência copiar agora — dois caminhos

Primeiro, reconheça o formato: o Request ID da APIYI começa com uma data e hora UTC de 14 dígitos. Por exemplo, em 2026111602224568279882196e93ae3kTS58ypN, os primeiros 14 dígitos 20261116022245 correspondem a 2026-11-16 02:22:45 UTC, ou seja, 10:22:45 no horário de Pequim. Compare esse prefixo com o horário da sua chamada e dá para saber basicamente se você pegou a string errada.

apiyi-request-id-docs-upgrade-pt-pt-image-1

Caminho um: copiar diretamente do JSON de erro

Este é o caminho indicado para a maioria dos usuários que usam cliente. Em caso de erro, no final do campo message do JSON de erro aparece um trecho (request id: ...); basta copiar a string completa entre parênteses.

  1. No cliente ou na saída de log, localize o JSON de erro completo.
  2. Localize o final do campo message.
  3. Copie toda a sequência de caracteres após request id:, sem truncar.

Logs do console: confirmam a chamada, mas não mostram o Request ID

Muita gente vai direto à página “Logs” do console para procurar o ID. A documentação nova dedica uma seção só para isso: a página de logs não exibe o X-Shellapi-Request-Id, e também não há um campo de busca por ele.

O que dá para ver nos logs: horário, modelo, nome do token, streaming/não streaming, tempo de execução, status, tokens de entrada/saída, custo, grupo, multiplicador e IP. Isso basta para confirmar se a chamada chegou à APIYI, qual modelo foi usado e quanto foi cobrado — mas não serve como referência para localizar um chamado de suporte.

Por isso, ao abrir um chamado, o ID vem de apenas duas fontes: o texto original do erro (caminho um) e os cabeçalhos da resposta (caminho dois). Os logs entram só para complementar os dados de horário, modelo, token e custo.

Caminho dois: ler os cabeçalhos de resposta no código

Se você faz coleta automatizada de erros, vale a pena registrar esse cabeçalho direto no código. Em todos os casos, a Base URL deve ser https://api.apiyi.com/v1.

  1. cURL: adicione curl -D headers.txt para gravar os cabeçalhos de resposta em um arquivo e depois procure x-shellapi-request-id nele. Para uma investigação rápida, dá para usar curl -i e imprimir na tela.
  2. Python requests: depois de obter o objeto de resposta, leia r.headers.get("x-shellapi-request-id"). Funciona tanto em caso de sucesso quanto de erro.
  3. OpenAI SDK (Python): o _request_id do retorno normal lê o x-request-id, que na APIYI normalmente vem vazio. O jeito certo é usar client.chat.completions.with_raw_response.create(...), ler raw.headers.get("x-shellapi-request-id") e depois chamar raw.parse() para obter o resultado. Em caso de erro, leia e.response.headers dentro do bloco except openai.APIStatusError as e.
  4. Node.js: com fetch, leia res.headers.get("x-shellapi-request-id").
  5. Postman: depois de enviar a requisição, abra a aba Headers na área de resposta e procure X-Shellapi-Request-Id.
  6. Frontend no navegador: chamadas cross-origin esbarram nas restrições de CORS e o JS não consegue ler esse cabeçalho. Nesse caso, registre no proxy do backend ou confira em DevTools → Network → a requisição → Response Headers.

🚀 Início rápido: para confirmar que seu código consegue ler esse cabeçalho, envie uma requisição mínima usando um token da APIYI apiyi.com e veja se aparece um ID começando com um timestamp de 14 dígitos. Esse passo consome alguns tokens, então prefira um comando com saída bem curta.

Quais IDs não são o Request ID do APIYI

Uma única resposta pode conter vários “IDs” ao mesmo tempo, e muitos tickets travam justamente nessa etapa. A documentação nova traz uma tabela comparativa, e abaixo resumo os pontos principais.

apiyi-request-id-docs-upgrade-pt-pt-image-2

Campo Origem Pode ser usado para abrir ticket e buscar logs Característica de identificação
X-Shellapi-Request-Id APIYI ✅ é esse mesmo Começa com data/hora UTC de 14 dígitos
X-Oneapi-Request-Id Camada intermediária ❌ Nome do cabeçalho diferente
X-Request-Id Fabricante upstream ❌ não aparece nos logs do APIYI Geralmente começa com req_ ou UUID
Outros cabeçalhos personalizados de canal Canal ❌ Nomes de cabeçalho variados
id no corpo da resposta Completion ID / Response ID ❌ Começa com chatcmpl- ou resp_
generation_id da imagem Resultado da geração de imagem ❌ Está no corpo da resposta
task_id Tarefa assíncrona ❌ não é Request ID, mas precisa ser informado junto Consultar tarefa, consultar cobrança

A regra é simples: se não começar com os 14 dígitos de data/hora, não é o Request ID do APIYI. Se o ID recebido começar com req_, a requisição pode ter ido direto para o OpenAI oficial. Nesse caso, verifique primeiro se a Base URL está escrita como https://api.apiyi.com/v1.


Como armazenar separadamente o task_id de vídeo assíncrono e o Request ID

O vídeo assíncrono tem duas etapas: “envio” e “consulta”. Cada etapa retorna um novo X-Shellapi-Request-Id, além de um ID de tarefa, o que facilita a confusão entre eles. A recomendação da documentação nova é: armazenar separadamente o Request ID do envio e o ID de tarefa usado no polling.

Modelo Local do ID de tarefa Endpoint de consulta Campo que causa confusão
Seedance id no nível superior do corpo da resposta (o campo não se chama task_id) GET /seedance/api/v3/contents/generations/tasks/{id} —
Wan / HappyHorse output.task_id GET /v1/tasks/{task_id} o request_id no corpo da resposta é do upstream, não é o que aparece nos logs do APIYI

Na prática, recomenda-se salvar três campos por tarefa: o X-Shellapi-Request-Id do envio, o ID de tarefa e o horário de envio. O Request ID retornado ao consultar a tarefa pode ser registrado conforme necessário. Em caso de falha no envio, use o Request ID para reportar o problema; quando a tarefa travar ou houver dúvida sobre cobrança, o ID de tarefa será necessário tanto para consultar a tarefa quanto para consultar a cobrança.


O que complementar quando o Request ID não aparece nos logs

Mesmo com o ID em mãos, não é garantido que ele apareça nos logs. A documentação mais recente separou uma seção só para “não há Request ID nos logs do console”; os outros casos em que não dá para encontrar o ID podem ser tratados conforme a tabela abaixo.

Situação Causa O que complementar
A requisição falha antes de receber uma resposta DNS, TCP/TLS, recusa do proxy, timeout do cliente, sem nenhum cabeçalho de resposta Mensagem de erro original, horário da chamada e descrição do ambiente de rede
O cliente mostra apenas “falha na requisição” O cliente não expõe o erro original Obtenha o ID pelo caminho 1 ou caminho 2; os logs só conseguem confirmar se a chamada chegou
O ID começa com req_ Pode ter ido para o OpenAI oficial Verifique a Base URL e tente novamente
Não é possível encontrar nem nos logs Fora do período de retenção, ou ID errado Confira o formato do ID; os logs mantêm apenas o mês atual e os dois meses calendário anteriores

Mais um ponto: a página do console não mostra o ID, mas a API de consulta de logs consegue consultar por request_id. A tabela abaixo é de uma verificação de chamada real em 2026-11-16, com os modelos deepseek-flash e gpt-image-2, com requisições enviadas para https://api.apiyi.com/v1.

Chamada Status HTTP Cabeçalho de resposta Resultado da consulta por request_id nos logs
deepseek-flash não streaming 200 Tem x-shellapi-request-id, não tem x-request-id Consulta exata retorna 1 registro de consumo
deepseek-flash streaming 200 Tem, e já pode ser lido antes do primeiro bloco data: —
gpt-image-2, size=999×999 400 Mesmo valor do request id no final da message 3 linhas de erro/retentativa, sem linha de consumo
Nome de modelo inexistente 503 Mesmo valor do request id no final da message Não retorna nenhuma linha

A conclusão é: a página de logs do console não mostra o Request ID, mas a API de consulta de logs consegue encontrar “linhas de consumo” e “linhas de erro” por request_id, e não dá para garantir que sempre existam. Requisições que chegaram ao canal e falharam do lado do canal (por exemplo, erro de parâmetro) deixam uma linha de erro. As que são rejeitadas na hora na camada de gateway (por exemplo, nenhum canal disponível) podem não deixar nenhuma linha. Quando não encontrar, use o ID que está no cabeçalho de resposta ou na mensagem de erro original, junto com o horário da chamada, para complementar as informações.

Se o suporte precisar reproduzir o problema, você pode fazer uma nova chamada na APIYI (apiyi.com) com o mesmo token e o mesmo conjunto de parâmetros, ou trocar por outro modelo para comparar se é o mesmo erro. Reproduzir também consome tokens, então lembre-se de registrar o Request ID de cada reprodução.

🎯 Sugestão de diagnóstico: ao reproduzir o erro, fixe a Base URL como https://api.apiyi.com/v1 e registre sempre o X-Shellapi-Request-Id e o horário da chamada. Depois, passe o ID e o horário da chamada para o suporte; o backend consulta pelo ID e consegue confirmar mais rápido se o erro aconteceu na camada de gateway ou na camada do canal.


Modelo de ticket de erro de Request ID da APIYI

Os campos abaixo podem ser copiados direto no ticket:

  • Request ID: aquela string que começa com 14 dígitos de data/hora
  • Modelo: ex.: gpt-image-2
  • Endpoint: ex.: POST /v1/chat/completions
  • Horário: com fuso horário, ex.: 2026-11-16 11:24:04 UTC+8
  • Status HTTP: ex.: 400 / 503
  • Mensagem de erro: cole o erro completo, incluindo (request id: ...)
  • O que já foi tentado: ex.: já troquei o modelo, já verifiquei a Base URL, já tentei 2 vezes
  • task_id (somente para vídeo assíncrono): o ID da tarefa retornado no envio

Atenção a dois pontos: não envie a chave API completa; se o corpo da requisição ou as imagens tiverem conteúdo privado, remova os dados sensíveis antes de enviar.


Impacto da atualização da documentação de Request ID para os desenvolvedores

Para os desenvolvedores

  • Menos uma rodada no report de problemas: informando o ID certo de primeira, o suporte não precisa voltar a perguntar.
  • Usuários de SDK não recebem mais valor vazio: ficou claro o problema do _request_id e como obtê-lo com with_raw_response.
  • Tarefas de vídeo rastreáveis: Request ID e ID da tarefa guardados separadamente, o que dá base tanto para consultar a tarefa quanto para consultar a cobrança.

Ao consultar a documentação antiga, fique atento

Em algumas páginas de recursos de endpoint, páginas de notícias e páginas que armazenam erros, o x-request-id ainda aparece como “registre isso para facilitar a investigação”. Quando encontrar esse tipo de afirmação, use a nova página de Request ID como referência. Nos templates de código, também substitua x-request-id por x-shellapi-request-id.


Perguntas Frequentes (FAQ)

Q1: Qual é exatamente o Request ID do APIYI?

É o X-Shellapi-Request-Id no cabeçalho de resposta, que começa com um timestamp UTC de 14 dígitos. Quando ocorre um erro, o valor dentro de `(request id: …)` no final da mensagem de erro é o mesmo que ele.

Q2: É seguro enviar o Request ID para outras pessoas?

É seguro. Conforme a documentação original, o Request ID não é uma chave e pode ser colado em tickets, chats ou capturas de tela. O que não pode ser compartilhado externamente é a chave API completa que começa com `sk-`.

Q3: Por que o ID lido pelo SDK da OpenAI fica vazio?

O `_request_id` padrão do SDK lê x-request-id. Basta usar `with_raw_response`, ou obter x-shellapi-request-id a partir do cabeçalho de resposta do `APIStatusError`.

Q4: Como verificar rapidamente se consigo obter o Request ID correto?

1. Cadastre-se em APIYI apiyi.com e obtenha uma chave API; novos usuários têm cota gratuita de teste.
2. Defina a URL base como `https://api.apiyi.com/v1` e envie uma requisição mínima.
3. Imprima x-shellapi-request-id e confirme se consegue obter essa string de ID a cada chamada; a página de logs só permite verificar se essa chamada chegou e se houve cobrança, mas não mostra o ID.

Q5: Ainda é possível consultar erros de três meses atrás?

Geralmente não. Os logs mantêm o mês atual e os dois meses naturais anteriores; registros mais antigos precisam ser explicados com o Request ID e o texto original do erro que você mesmo guardou.


Pontos-chave do Request ID da APIYI (Key Takeaways)

  • O único ID correto: X-Shellapi-Request-Id, que começa com um horário UTC de 14 dígitos
  • Duas formas de obtê-lo: copiar da mensagem de erro ou ler o cabeçalho de resposta no código (os logs só confirmam a chamada, não mostram o ID)
  • Capturas erradas comuns: X-Request-Id, req_, chatcmpl-, resp_ e UUID não servem para abrir chamado
  • Para vídeo, salve dois: guarde separadamente o Request ID enviado e o ID da tarefa
  • Os logs não são 100%: a página do console não mostra o ID; requisições rejeitadas na hora pelo gateway podem nem ter registro — nesse caso, complemente com o texto original do erro e o horário
  • Validação na prática: faça uma requisição mínima em APIYI apiyi.com para confirmar que consegue ler esse cabeçalho

Resumo

A atualização da documentação de consulta do Request ID da APIYI gira em torno de três coisas:

  1. Resposta em primeiro lugar: o Request ID é o X-Shellapi-Request-Id, e o mesmo valor também aparece no final da mensagem de erro.
  2. Exclusão de IDs errados: a tabela comparativa deixa clara a diferença entre a camada intermediária, o upstream, o corpo da resposta e o ID da tarefa.
  3. Plano B quando não encontrar: para cada um dos quatro casos, mostra quais materiais complementar, com um modelo de ticket pronto para usar.

Sugiro que você já altere agora o campo de log de erro no código para x-shellapi-request-id. Depois, se surgir algum problema, passe o ID junto com o horário da chamada para o suporte; o back-end consulta pelo ID, e então você abre o ticket com os materiais completos.


📚 Referências

  1. Documentação de diagnóstico do Request ID da APIYI (nova versão) — base factual deste artigo
  2. Link: docs.apiyi.com/faq/request-id-troubleshooting
  3. Descrição: inclui duas formas de obter o ID, explicação dos logs do console, tabela de correspondência de IDs, instruções sobre vídeos assíncronos e modelo de ticket

  4. Por quanto tempo os logs são mantidos — explicação do período de retenção de logs

  5. Link: docs.apiyi.com/faq/log-retention-policy
  6. Descrição: confirma se os registros de erro ainda podem ser consultados

Autor: Equipe técnica da APIYI
Contato técnico: fique à vontade para falar conosco pela página inicial do site APIYI apiyi.com. Ao abrir um ticket, inclua o X-Shellapi-Request-Id para agilizar o atendimento.

Similar Posts