Guías principales

Registros y resolución de problemas

Conserve los ID necesarios para rastrear solicitudes, tareas y cargos

Mantenga los ID de solicitud, tarea y facturación de TokenLab en sus registros. Estos conectan una acción del usuario con su resultado y cargo sin almacenar el prompt ni contenido multimedia privado.

En la consola, los detalles capturados de las solicitudes y respuestas están disponibles durante 30 días a partir de su captura, y el acceso finaliza exactamente en el momento del vencimiento, incluso si la limpieza física aún está en cola. La identidad de la solicitud y el historial de facturación/uso tienen ciclos de vida independientes. Consulte Retención de datos.

De una solicitud a una investigación y soporte

  1. Abra Runs en el espacio de trabajo al que pertenece la solicitud. Busque su Request ID y seleccione la fila.

  2. Elija Open full details para acceder a una página dedicada. Back to requests restaura los filtros de la lista. Un enlace nunca otorga acceso a otro espacio de trabajo; utilice una cuenta autorizada para dicho espacio de trabajo.

  3. Para estados pendientes o desconocidos, actualice primero el progreso. Para una respuesta fallida o interrumpida, elija Investigate the issue cuando esté disponible. Esto inicia una investigación para esa solicitud en el Agent dentro de la aplicación; no vuelve a ejecutar la solicitud original del modelo. Las solicitudes exitosas no necesitan una investigación de forma predeterminada.

  4. Si aún necesita ayuda, elija la acción de soporte humano desde la solicitud o investigación. Se abrirá una vista previa con la solicitud y la conversación vinculadas cuando estén disponibles. Revise el resumen y elimine el contenido privado, luego seleccione explícitamente Submit. Una investigación o una vista previa por sí solas no envían una solicitud de soporte.

  5. Después del envío, guarde la confirmación y continúe la misma conversación en Support. Reutilícela para respuestas e información adicional en lugar de enviar duplicados.

ID que debe conservar

IdentificadorDónde apareceÚselo para
request_idCuerpos de error, registros del panel, registros de usoSoporte a nivel de solicitud y conciliación
id / task_idRespuestas de creación asíncrona y estadoConsultar cualquier trabajo asíncrono con GET /v1/tasks/{id}
poll_urlRespuestas de creación asíncronaURL de estado; consulte /v1/tasks/{id} con id
billing_transaction_idRespuestas sin streaming cuando se liquidan, respuestas de estado de tareas asíncronas, registros de uso, X-Billing-Transaction-IDConciliación de costos
X-Task-IDEncabezados de respuesta de tareas asíncronasCorrelación de tareas a nivel de encabezado
Su propio ID de trabajo/usuarioSu aplicaciónEncontrar la solicitud de TokenLab para una acción de usuario

Los registros orientados al cliente deben usar los ID de TokenLab. Nunca exponga URL de servicios privados, claves de caché o metadatos de diagnóstico.

Qué registrar

Registre lo suficiente para diagnosticar la solicitud sin filtrar secretos:

  • Endpoint, método HTTP, modelo, código de estado, marca de tiempo y latencia.
  • Identificadores públicos: request_id, task_id, poll_url y billing_transaction_id cuando estén presentes.
  • Nombres de campos enviados en la solicitud, no el prompt completo ni contenido multimedia privado.
  • Respuestas finales de estado asíncrono y campos de error seguros.
  • Recuento de reintentos del cliente y si el reintento creó una nueva tarea o reanudó una existente.

Redacte siempre Authorization, claves de API, tokens de gestión, URL firmadas, URL de medios privados, prompts completos y datos personales del usuario, a menos que tenga permiso explícito para conservarlos.

Matriz de resolución de problemas

SíntomaPrimera verificaciónPágina útil
401 o 403Clave de API, token de gestión, acceso a la organización, alcance de la claveAutenticación
402Saldo, límite de gasto de la clave de APIFacturación y precios
429Nivel de cuenta, límite de tasa del endpoint, comportamiento de reintentoLímites de tasa
400 invalid_request_errorCampo no admitido, endpoint incorrecto, campo obligatorio faltante o discrepancia en la solicitud del modeloManejo de errores
No se encuentra la tarea asíncronaClave de API incorrecta, ID mal escrito o tarea expiradaTrabajos asíncronos y sondeo
El costo no coincide con la UITiempo de liquidación o comparación del identificador incorrectoFacturación y precios

Conciliación de uso

Utilice la API de gestión para la conciliación del lado del 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 puede filtrar por scene, model, modelVendor, startDate y endDate. Utilice estos registros en lugar de extraer datos de las páginas de la consola o calcular cargos solo a partir de los recuentos de tokens de respuesta. Una endDate solo con fecha significa 00:00 UTC al inicio de ese día; consulte Obtener uso de clave de API.

Las respuestas de streaming pueden liquidarse después de que se envíe el stream, por lo que un encabezado de facturación puede estar ausente incluso cuando el uso se registra posteriormente. Las tareas multimedia asíncronas pueden liquidarse después del sondeo terminal.

Qué enviar a soporte

Al contactar a soporte, incluya:

  • request_id.
  • task_id y poll_url para trabajos asíncronos.
  • billing_transaction_id cuando esté presente.
  • Endpoint, método, modelo, marca de tiempo y código de estado.
  • Nombres de campos de solicitud y el cuerpo de error seguro.
  • Su resultado esperado y lo que el usuario vio realmente.

No incluya claves de API, tokens de gestión, medios privados, prompts completos, URL de servicios privados o identificadores de diagnóstico. Si soporte necesita un ejemplo de solicitud, envíe una copia redactada.

Verificaciones que vale la pena automatizar

  • Alerte sobre respuestas 401, 402, 429 y 5xx repetidas por separado; cada una requiere una respuesta diferente.
  • Realice un seguimiento de los trabajos asíncronos que permanecen en estado no terminal durante más tiempo que su SLA de producto.
  • Realice un seguimiento de los intentos de creación duplicados para el mismo ID de trabajo de usuario.
  • Muestree los trabajos completados y verifique que el activo visible para el usuario, el registro de uso y el registro de tarea almacenado coincidan.

Referencia de API

TemaReferencia
Manejo de erroresManejo de errores
Límites de tasaLímites de tasa
Facturación y preciosFacturación y precios
Obtener uso de clave de APIObtener uso de clave de API
Obtener estado de tareaObtener estado de tarea

En esta página