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
-
Abra Execuções no workspace que possui a requisição. Encontre o seu Request ID e selecione a linha.
-
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.
-
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.
-
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.
-
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
| Identificador | Onde aparece | Use para |
|---|---|---|
request_id | Corpos de erro, logs do dashboard, registros de uso | Suporte em nível de requisição e reconciliação |
id / task_id | Respostas de criação assíncrona e status | Sondagem (polling) de qualquer job assíncrono com GET /v1/tasks/{id} |
poll_url | Respostas de criação assíncrona | URL de status; faça polling em /v1/tasks/{id} com id |
billing_transaction_id | Respostas sem streaming quando liquidadas, respostas de status de tarefa assíncrona, registros de uso, X-Billing-Transaction-ID | Reconciliação de custos |
X-Task-ID | Cabeçalhos de resposta de tarefa assíncrona | Correlação de tarefa em nível de cabeçalho |
| Seu próprio ID de job/usuário | Sua aplicação | Encontrar 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_urlebilling_transaction_idquando 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
| Sintoma | Primeira verificação | Página útil |
|---|---|---|
401 ou 403 | Chave de API, token de gerenciamento, acesso à organização, escopo da chave | Autenticação |
402 | Saldo, limite de gastos da chave de API | Faturamento e Preços |
429 | Nível da conta, limite de taxa do endpoint, comportamento de retry | Limites de Taxa |
400 invalid_request_error | Campo não suportado, endpoint incorreto, campo obrigatório ausente ou incompatibilidade na requisição do modelo | Tratamento de Erros |
| Tarefa assíncrona não encontrada | Chave de API incorreta, ID digitado incorretamente ou tarefa expirada | Jobs Assíncronos e Polling |
| Custo não corresponde à UI | Tempo de liquidação ou comparação do identificador incorreto | Faturamento 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_idepoll_urlpara trabalhos assíncronos.billing_transaction_idquando 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,429e5xxrepetidas 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ópico | Referência |
|---|---|
| Tratamento de Erros | Tratamento de Erros |
| Limites de Taxa | Limites de Taxa |
| Faturamento e Preços | Faturamento e Preços |
| Obter Uso da Chave de API | Obter Uso da Chave de API |
| Obter Status da Tarefa | Obter Status da Tarefa |