Guías principales
Observabilidad y Solución de Problemas
Registra los identificadores públicos de TokenLab necesarios para soporte, conciliación de uso y depuración de medios asíncronos.
Una buena observabilidad de TokenLab comienza con identificadores públicos. Tus registros deberían ayudarte a responder "¿qué solicitó el usuario, qué tarea pública creó TokenLab y cómo se facturó?" sin exponer detalles sensibles del proveedor ni datos sensibles del usuario.
De la solicitud al diagnóstico y al soporte
-
Abre Solicitudes en el espacio de trabajo propietario. Busca el Request ID y selecciona la fila.
-
Abre los detalles completos en una página independiente. Al volver a la lista se restauran los filtros. Un enlace no concede acceso a otro espacio; usa una cuenta autorizada.
-
Si el estado está pendiente o es desconocido, actualiza primero el progreso. Ante un fallo o una respuesta interrumpida, inicia la investigación disponible en el Agent integrado. No vuelve a enviar la solicitud original al modelo. Las solicitudes correctas no necesitan investigación por defecto.
-
Si necesitas ayuda, elige soporte humano desde la solicitud o investigación. Revisa la vista previa y los enlaces a la solicitud y conversación cuando estén disponibles, elimina datos privados y envía explícitamente. Abrir una investigación o vista previa no envía una solicitud al soporte.
-
Guarda la confirmación y continúa la misma conversación en Soporte para recibir respuestas y añadir información, evitando duplicados.
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 |
No almacenes IDs de tareas del proveedor, URLs del proveedor, identificadores del proveedor, claves de Redis o metadatos de ejecución sensibles como registros visibles para el cliente.
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.
Siempre redacta 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 detalle 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:
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. 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.
No incluyas claves de API, tokens de gestión, medios privados, prompts completos, URLs del proveedor, IDs de canales o identificadores privados de diagnóstico a menos que el soporte de TokenLab solicite explícitamente una muestra redactada.
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 |