Guias principais

Logs e solução de problemas

Mantenha os IDs necessários para rastrear requisições, tarefas e cobranças

Mantenha os IDs de requisição, tarefa e faturamento do TokenLab em seus logs. Eles conectam uma ação do usuário ao seu resultado e cobrança, sem armazenar o prompt ou mídia privada.

No Console, os detalhes capturados de requisições e respostas ficam disponíveis por 30 dias a partir da captura, com o acesso encerrando exatamente no momento da expiração, mesmo que a limpeza física ainda esteja na fila. A identidade da requisição e o histórico de faturamento/uso possuem tempos de vida independentes. Veja Retenção de dados.

De uma requisição a uma investigação e suporte

  1. Abra Execuções no workspace que possui a requisição. Encontre o seu Request ID e selecione a linha.

  2. Escolha Abrir detalhes completos para uma página dedicada. Voltar para requisições restaura os filtros da lista. Um link nunca concede acesso a outro workspace; use uma conta autorizada para aquele workspace.

  3. Para status pendente ou desconhecido, atualize o progresso primeiro. Para uma falha ou resposta interrompida, escolha Investigar o problema quando disponível. Isso inicia uma investigação para aquela requisição no Agent in-app; isso não reexecuta a requisição original do modelo. Requisições bem-sucedidas não precisam de investigação por padrão.

  4. Se você ainda precisar de ajuda, escolha a ação de suporte humano a partir da requisição ou investigação. Isso abre uma visualização com a requisição e a conversa vinculadas, quando disponíveis. Revise o resumo e remova conteúdo privado, então selecione explicitamente Enviar. Uma investigação ou uma visualização por si só não envia uma solicitação de suporte.

  5. Após o envio, guarde a confirmação e continue a mesma conversa em Suporte. Reutilize-a para respostas e informações adicionais em vez de enviar duplicatas.

IDs para manter

IdentificadorOnde apareceUse para
request_idCorpos de erro, logs do dashboard, registros de usoSuporte em nível de requisição e reconciliação
id / task_idRespostas de criação assíncrona e statusSondagem (polling) de qualquer job assíncrono com GET /v1/tasks/{id}
poll_urlRespostas de criação assíncronaURL de status; faça polling em /v1/tasks/{id} com id
billing_transaction_idRespostas sem streaming quando liquidadas, respostas de status de tarefa assíncrona, registros de uso, X-Billing-Transaction-IDReconciliação de custos
X-Task-IDCabeçalhos de resposta de tarefa assíncronaCorrelação de tarefa em nível de cabeçalho
Seu próprio ID de job/usuárioSua aplicaçãoEncontrar a requisição TokenLab para uma ação do usuário

Registros voltados ao cliente devem usar IDs do TokenLab. Nunca exponha URLs de serviço privadas, chaves de cache ou metadados de diagnóstico.

O que registrar

Registre o suficiente para diagnosticar a requisição sem vazar segredos:

  • Endpoint, método HTTP, modelo, código de status, timestamp e latência.
  • Identificadores públicos: request_id, task_id, poll_url e billing_transaction_id quando presentes.
  • Nomes dos campos enviados na requisição, não o prompt completo ou conteúdo de mídia privada.
  • Respostas finais de status assíncrono e campos de erro seguros.
  • Contagem de tentativas do cliente e se a tentativa criou uma nova tarefa ou retomou uma existente.

Sempre oculte Authorization, chaves de API, tokens de gerenciamento, URLs assinadas, URLs de mídia privada, prompts completos e dados pessoais do usuário, a menos que você tenha permissão explícita para retê-los.

Matriz de solução de problemas

SintomaPrimeira verificaçãoPágina útil
401 ou 403Chave de API, token de gerenciamento, acesso à organização, escopo da chaveAutenticação
402Saldo, limite de gastos da chave de APIFaturamento e Preços
429Nível da conta, limite de taxa do endpoint, comportamento de retryLimites de Taxa
400 invalid_request_errorCampo não suportado, endpoint incorreto, campo obrigatório ausente ou incompatibilidade na requisição do modeloTratamento de Erros
Tarefa assíncrona não encontradaChave de API incorreta, ID digitado incorretamente ou tarefa expiradaJobs Assíncronos e Polling
Custo não corresponde à UITempo de liquidação ou comparação do identificador incorretoFaturamento e Preços

Reconciliação de uso

Use a API de Gerenciamento para reconciliação no lado do servidor:

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
  -H "Authorization: Bearer mt-your-management-token"

GET /v1/management/api-keys/{keyId}/usage pode filtrar por scene, model, modelVendor, startDate e endDate. Use esses registros em vez de fazer scraping das páginas do Console ou calcular cobranças apenas pela contagem de tokens de resposta. Um endDate apenas com data significa 00:00 UTC no início daquele dia; veja Obter Uso da Chave de API.

Respostas de streaming podem ser liquidadas após o envio do stream, portanto, um cabeçalho de faturamento pode estar ausente mesmo quando o uso é registrado posteriormente. Tarefas de mídia assíncronas podem ser liquidadas após o polling terminal.

O que enviar ao suporte

Ao entrar em contato com o suporte, inclua:

  • request_id.
  • task_id e poll_url para trabalhos assíncronos.
  • billing_transaction_id quando presente.
  • Endpoint, método, modelo, timestamp e código de status.
  • Nomes dos campos da requisição e o corpo do erro seguro.
  • Seu resultado esperado e o que o usuário realmente viu.

Não inclua chaves de API, tokens de gerenciamento, mídia privada, prompts completos, URLs de serviço privadas ou identificadores de diagnóstico. Se o suporte precisar de um exemplo de requisição, envie uma cópia editada.

Verificações que valem a pena automatizar

  • Alerte sobre respostas 401, 402, 429 e 5xx repetidas separadamente; cada uma precisa de uma resposta diferente.
  • Rastreie jobs assíncronos que permanecem não terminais por mais tempo do que o SLA do seu produto.
  • Rastreie tentativas de criação duplicadas para o mesmo ID de job do usuário.
  • Faça amostragem de jobs concluídos e verifique se o ativo visível ao usuário, o registro de uso e o registro de tarefa armazenado estão de acordo.

Referência da API

TópicoReferência
Tratamento de ErrosTratamento de Erros
Limites de TaxaLimites de Taxa
Faturamento e PreçosFaturamento e Preços
Obter Uso da Chave de APIObter Uso da Chave de API
Obter Status da TarefaObter Status da Tarefa

Nesta página