Identificadores Públicos a Capturar
| Identificador | Onde aparece | Use para |
|---|---|---|
request_id | Corpos de erro, logs de dashboard, registros de uso | Suporte e reconciliação em nível de solicitação |
id / task_id | Respostas de criação assíncrona e status | Polling de trabalhos de imagem, vídeo, música e 3D |
poll_url | Respostas de criação assíncrona | URL de status preferida |
billing_transaction_id | Respostas não 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 trabalho/usuário | Seu aplicativo | Vinculando a atividade do TokenLab de volta ao fluxo de trabalho do usuário |
O Que Registrar
Registre o suficiente para diagnosticar a solicitaçã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. - Forma da solicitação sanitizada: quais campos estavam presentes, não o prompt completo ou conteúdo de mídia privada.
- Respostas de status assíncronas terminais, incluindo campos de erro públicos.
- Contagem de tentativas do cliente e se a tentativa criou uma nova tarefa ou retomou uma existente.
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, disponibilidade de preço do modelo | Cobrança & Preços |
429 | Nível da conta, limite de taxa do endpoint, comportamento de nova tentativa | Limites de Taxa |
400 invalid_request_error | Campo não suportado, endpoint errado, campo obrigatório ausente ou incompatibilidade de contrato do modelo | Tratamento de Erros |
| Tarefa assíncrona não pode ser encontrada | Chave de API errada, ID de tarefa desatualizado, tarefa expirada ou ID de tarefa não pública | Trabalhos Assíncronos & Polling |
| Custo não corresponde à UI | Tempo de liquidação ou comparação do identificador errado | Cobrança & Preços |
Reconciliação de Uso
Use a API de Gerenciamento para reconciliação do lado do servidor:GET /v1/management/api-keys/{keyId}/usage pode filtrar por scene, accessChannel, logicalModel, modelVendor, startDate e endDate. Use esses registros em vez de raspar páginas de dashboard ou depender de IDs de tarefas do provedor upstream.
Respostas de streaming podem ser liquidadas após o envio do stream, portanto, um cabeçalho de cobrança pode estar ausente mesmo quando o uso é registrado posteriormente. Tarefas de mídia assíncronas podem ser liquidadas após polling terminal.
Modelo de Pacote de Suporte
Ao entrar em contato com o suporte, inclua:request_id.task_idepoll_urlpara trabalho assíncrono.billing_transaction_idquando presente.- Endpoint, método, modelo, timestamp e código de status.
- Forma da solicitação sanitizada e corpo de erro público.
- Seu resultado esperado e o que o usuário realmente viu.
Verificações Operacionais
- Alerta sobre respostas repetidas
401,402,429e5xxseparadamente; geralmente têm proprietários diferentes. - Acompanhe trabalhos assíncronos que permanecem não terminais por mais tempo do que seu SLA de produto.
- Acompanhe tentativas de criação duplicadas para o mesmo ID de trabalho do usuário.
- Amostre trabalhos concluídos e verifique se o ativo visível para o usuário, o registro de uso e o registro de tarefa armazenado concordam.
Referência da API
| Tópico | Referência |
|---|---|
| Tratamento de Erros | Tratamento de Erros |
| Limites de Taxa | Limites de Taxa |
| Cobrança & Preços | Cobrança & Preços |
| Obter Uso da Chave de API | Obter Uso da Chave de API |
| Obter Status da Tarefa | Obter Status da Tarefa |