Identificadores Públicos a Capturar
| Identificador | Dónde aparece | Úsalo para |
|---|---|---|
request_id | Cuerpos de error, registros del panel, registros de uso | Soporte y conciliación a nivel de solicitud |
id / task_id | Respuestas de creación y estado asíncronas | Sondeo de trabajos de imagen, video, música y 3D |
poll_url | Respuestas de creación asíncronas | URL de estado preferida |
billing_transaction_id | Respuestas no de streaming cuando se liquidan, respuestas de estado de tareas asíncronas, registros de uso, X-Billing-Transaction-ID | Conciliación de costos |
X-Task-ID | Encabezados de respuesta de tareas asíncronas | Correlación de tareas a nivel de encabezado |
| Tu propio ID de trabajo/usuario | Tu aplicación | Unir la actividad de TokenLab de nuevo al flujo de trabajo del usuario |
Qué Registrar
Registra 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_urlybilling_transaction_idcuando estén presentes. - Forma de solicitud sanitizada: qué campos estaban presentes, no el prompt completo o contenido de medios privados.
- Respuestas de estado asíncronas terminales, incluidos campos de error públicos.
- Conteo de reintentos del cliente y si el reintento creó una nueva tarea o reanudó una existente.
Authorization, claves de API, tokens de gestión, URLs firmadas, URLs de medios privados, prompts completos y datos personales del usuario a menos que tengas permiso explícito para retenerlos.
Matriz de Solución de Problemas
| Síntoma | Primera verificación | Página útil |
|---|---|---|
401 o 403 | Clave de API, token de gestión, acceso a la organización, alcance de la clave | Autenticación |
402 | Saldo, límite de gasto de clave de API, disponibilidad de precio del modelo | Facturación y Precios |
429 | Nivel de cuenta, límite de tasa del endpoint, comportamiento de reintento | Límites de Tasa |
400 invalid_request_error | Campo no soportado, endpoint incorrecto, campo requerido faltante o desajuste de contrato del modelo | Manejo de Errores |
| No se puede encontrar la tarea asíncrona | Clave de API incorrecta, ID de tarea obsoleto, tarea expirada o ID de tarea no pública | Trabajos Asíncronos y Sondeo |
| El costo no coincide con la UI | Tiempo de liquidación o comparación del identificador incorrecto | Facturación y Precios |
Conciliación de Uso
Utiliza la API de Gestión para la conciliación del lado del servidor:GET /v1/management/api-keys/{keyId}/usage puede filtrar por scene, accessChannel, logicalModel, modelVendor, startDate y endDate. Utiliza estos registros en lugar de raspar páginas del panel o depender de IDs de tareas del proveedor ascendente.
Las respuestas de streaming pueden liquidarse después de que se envía el stream, por lo que un encabezado de facturación puede estar ausente incluso cuando el uso se registra más tarde. Las tareas de medios asíncronas pueden liquidarse después del sondeo terminal.
Plantilla de Paquete de Soporte
Al contactar soporte, incluye:request_id.task_idypoll_urlpara trabajos asíncronos.billing_transaction_idcuando esté presente.- Endpoint, método, modelo, marca de tiempo y código de estado.
- Forma de solicitud sanitizada y cuerpo de error público.
- Tu resultado esperado y lo que el usuario realmente vio.
Comprobaciones Operativas
- Alerta sobre respuestas repetidas
401,402,429y5xxpor separado; generalmente tienen diferentes propietarios. - Rastrea trabajos asíncronos que permanecen no terminales más allá de tu SLA de producto.
- Rastrea intentos de creación duplicados para el mismo ID de trabajo de usuario.
- Muestra trabajos completados y verifica que el activo visible para el usuario, el registro de uso y el registro de tarea almacenado coincidan.
Referencia de API
| Tema | Referencia |
|---|---|
| Manejo de Errores | Manejo de Errores |
| Límites de Tasa | Límites de Tasa |
| Facturación y Precios | Facturación y Precios |
| Obtener Uso de Clave de API | Obtener Uso de Clave de API |
| Obtener Estado de Tarea | Obtener Estado de Tarea |