Skip to main content
Good TokenLab observability starts with public identifiers. Your logs should help you answer “what did the user request, what public task did TokenLab create, and how was it billed?” without exposing provider routing internals or sensitive user data.

​
Public Identifiers To Capture

IdentifierWhere it appearsUse it for
request_idError bodies, dashboard logs, usage recordsRequest-level support and reconciliation
id / task_idAsync create and status responsesPolling image, video, music, and 3D jobs
poll_urlAsync create responsesPreferred status URL
billing_transaction_idNon-streaming responses when settled, async task status responses, usage records, X-Billing-Transaction-IDCost reconciliation
X-Task-IDAsync task response headersHeader-level task correlation
Your own job/user IDYour applicationJoining TokenLab activity back to the user workflow
Do not store provider task IDs, upstream URLs, routing channel IDs, Redis keys, or private execution metadata as customer-facing truth.

​
What To Log

Log enough to diagnose the request without leaking secrets:
  • Endpoint, HTTP method, model, status code, timestamp, and latency.
  • Public identifiers: request_id, task_id, poll_url, and billing_transaction_id when present.
  • Sanitized request shape: which fields were present, not the full prompt or private media content.
  • Terminal async status responses, including public error fields.
  • Client retry count and whether the retry created a new task or resumed an existing one.
Always redact Authorization, API keys, management tokens, signed URLs, private media URLs, full prompts, and user personal data unless you have explicit permission to retain them.

​
Troubleshooting Matrix

SymptomFirst checkUseful page
401 or 403API key, management token, organization access, key scopeAuthentication
402Balance, API key spend limit, model price availabilityBilling & Pricing
429Account tier, endpoint rate limit, retry behaviorRate Limits
400 invalid_request_errorUnsupported field, wrong endpoint, missing required field, or model contract mismatchError Handling
Async task cannot be foundWrong API key, stale task ID, expired task, or non-public task IDAsync Jobs & Polling
Cost does not match UISettlement timing or comparing the wrong identifierBilling & Pricing

​
Usage Reconciliation

Use the Management API for server-side reconciliation: 
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 can filter by scene, accessChannel, logicalModel, modelVendor, startDate, and endDate. Use these records instead of scraping dashboard pages or relying on upstream provider task IDs. Streaming responses may settle after the stream is sent, so a billing header can be absent even when usage is later recorded. Async media tasks may settle after terminal polling.

​
Support Packet Template

When contacting support, include:
  • request_id.
  • task_id and poll_url for async work.
  • billing_transaction_id when present.
  • Endpoint, method, model, timestamp, and status code.
  • Sanitized request shape and public error body.
  • Your expected result and what the user actually saw.
Do not include API keys, management tokens, private media, full prompts, provider URLs, channel IDs, or internal routing identifiers unless TokenLab support explicitly asks for a redacted sample.

​
Operational Checks

  • Alert on repeated 401, 402, 429, and 5xx responses separately; they usually have different owners.
  • Track async jobs that remain non-terminal longer than your product SLA.
  • Track duplicate create attempts for the same user job ID.
  • Sample completed jobs and verify the user-visible asset, usage record, and stored task record agree.

​
API Reference

TopicReference
Error HandlingError Handling
Rate LimitsRate Limits
Billing & PricingBilling & Pricing
Get API Key UsageGet API Key Usage
Get Task StatusGet Task Status