Kernleitfäden

Logs und Fehlerbehebung

Bewahren Sie die IDs auf, die zur Nachverfolgung von Anfragen, Tasks und Abrechnungen erforderlich sind

Speichern Sie TokenLab-Anfrage-, Task- und Abrechnungs-IDs in Ihren Logs. Sie verknüpfen eine Benutzeraktion mit ihrem Ergebnis und der Abrechnung, ohne den Prompt oder private Medien zu speichern.

In der Console sind erfasste Anfrage- und Antwortdetails 30 Tage lang ab der Erfassung verfügbar. Der Zugriff endet exakt zum Ablaufdatum, auch wenn die physische Bereinigung noch in der Warteschlange steht. Die Identität der Anfrage sowie die Abrechnungs- und Nutzungshistorie haben unabhängige Lebenszyklen. Siehe Datenaufbewahrung.

Von der Anfrage zur Untersuchung und zum Support

  1. Öffnen Sie Runs in dem Workspace, zu dem die Anfrage gehört. Suchen Sie die Request ID und wählen Sie die Zeile aus.

  2. Wählen Sie Open full details für eine dedizierte Seite. Back to requests stellt die Listenfilter wieder her. Ein Link gewährt niemals Zugriff auf einen anderen Workspace; verwenden Sie ein Konto, das für diesen Workspace autorisiert ist.

  3. Aktualisieren Sie bei einem ausstehenden oder unbekannten Status zuerst den Fortschritt. Wählen Sie bei einem Fehler oder einer unterbrochenen Antwort Investigate the issue, sofern verfügbar. Dies startet eine Untersuchung für diese Anfrage im In-App-Agent; das ursprüngliche Modell-Request wird dabei nicht erneut ausgeführt. Erfolgreiche Anfragen benötigen standardmäßig keine Untersuchung.

  4. Wenn Sie weiterhin Hilfe benötigen, wählen Sie die Human-Support-Aktion aus der Anfrage oder Untersuchung. Dies öffnet eine Vorschau mit der verknüpften Anfrage und dem Gespräch, sofern verfügbar. Überprüfen Sie die Zusammenfassung, entfernen Sie private Inhalte und wählen Sie explizit Submit. Eine Untersuchung oder eine Vorschau allein sendet noch keine Support-Anfrage.

  5. Bewahren Sie nach dem Absenden die Bestätigung auf und führen Sie dasselbe Gespräch unter Support fort. Verwenden Sie es für Antworten und zusätzliche Informationen, anstatt Duplikate einzureichen.

IDs zum Aufbewahren

IdentifikatorWo er erscheintVerwendung für
request_idFehler-Bodies, Dashboard-Logs, NutzungsdatensätzeSupport auf Anfrageebene und Abgleich
id / task_idAsync-Erstellungs- und StatusantwortenAbfragen (Polling) jedes Async-Jobs mit GET /v1/tasks/{id}
poll_urlAsync-ErstellungsantwortenStatus-URL; Abfrage von /v1/tasks/{id} mit id
billing_transaction_idNicht-Streaming-Antworten nach Abrechnung, Async-Task-Statusantworten, Nutzungsdatensätze, X-Billing-Transaction-IDKostenabgleich
X-Task-IDAntwort-Header von Async-TasksTask-Korrelation auf Header-Ebene
Ihre eigene Job-/User-IDIhre AnwendungAuffinden der TokenLab-Anfrage für eine Benutzeraktion

Kundenorientierte Datensätze sollten TokenLab-IDs verwenden. Geben Sie niemals private Service-URLs, Cache-Keys oder Diagnose-Metadaten preis.

Was zu protokollieren ist

Protokollieren Sie genügend Informationen, um die Anfrage zu diagnostizieren, ohne Geheimnisse preiszugeben:

  • Endpunkt, HTTP-Methode, Modell, Statuscode, Zeitstempel und Latenz.
  • Öffentliche Identifikatoren: request_id, task_id, poll_url und billing_transaction_id, sofern vorhanden.
  • Feldnamen, die in der Anfrage gesendet wurden, nicht den vollständigen Prompt oder private Medieninhalte.
  • Abschließende Async-Statusantworten und sichere Fehlerfelder.
  • Anzahl der Client-Wiederholungsversuche (Retries) und ob der Wiederholungsversuch einen neuen Task erstellt oder einen bestehenden fortgesetzt hat.

Schwärzen Sie immer Authorization, API-Keys, Management-Token, signierte URLs, private Medien-URLs, vollständige Prompts und persönliche Benutzerdaten, es sei denn, Sie haben die ausdrückliche Erlaubnis, diese aufzubewahren.

Matrix zur Fehlerbehebung

SymptomErster CheckNützliche Seite
401 oder 403API-Key, Management-Token, Organisationszugriff, Key-ScopeAuthentifizierung
402Guthaben, Ausgabenlimit des API-KeysAbrechnung & Preise
429Kontostufe, Endpunkt-Ratenlimit, WiederholungsverhaltenRatenlimits
400 invalid_request_errorNicht unterstütztes Feld, falscher Endpunkt, fehlendes Pflichtfeld oder Modell-Anfrage-KonfliktFehlerbehandlung
Async-Task nicht gefundenFalscher API-Key, falsch geschriebene ID oder abgelaufener TaskAsync-Jobs & Polling
Kosten stimmen nicht mit UI übereinAbrechnungszeitpunkt oder Vergleich des falschen IdentifikatorsAbrechnung & Preise

Nutzungsabgleich

Verwenden Sie die Management API für den serverseitigen Abgleich:

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 kann nach scene, model, modelVendor, startDate und endDate filtern. Verwenden Sie diese Datensätze anstelle des Scrapings von Console-Seiten oder der Berechnung von Kosten allein aus den Token-Anzahlen der Antworten. Ein endDate ohne Zeitangabe bedeutet 00:00 UTC am Beginn dieses Tages; siehe API-Schlüssel-Nutzung abrufen.

Streaming-Antworten können abgerechnet werden, nachdem der Stream gesendet wurde, sodass ein Abrechnungs-Header fehlen kann, auch wenn die Nutzung später erfasst wird. Async-Medien-Tasks können nach dem abschließenden Polling abgerechnet werden.

Was an den Support zu senden ist

Geben Sie bei der Kontaktaufnahme mit dem Support Folgendes an:

  • request_id.
  • task_id und poll_url für Async-Arbeiten.
  • billing_transaction_id, sofern vorhanden.
  • Endpunkt, Methode, Modell, Zeitstempel und Statuscode.
  • Anfrage-Feldnamen und den sicheren Fehler-Body.
  • Ihr erwartetes Ergebnis und was der Benutzer tatsächlich gesehen hat.

Fügen Sie keine API-Keys, Management-Token, privaten Medien, vollständigen Prompts, privaten Service-URLs oder Diagnose-Identifikatoren bei. Wenn der Support ein Anfragebeispiel benötigt, senden Sie eine geschwärzte Kopie.

Zu automatisierende Prüfungen

  • Alarmierung bei wiederholten 401-, 402-, 429- und 5xx-Antworten; jede erfordert eine andere Reaktion.
  • Nachverfolgung von Async-Jobs, die länger als Ihr Produkt-SLA in einem nicht-terminalen Status verbleiben.
  • Nachverfolgung doppelter Erstellungsversuche für dieselbe Benutzer-Job-ID.
  • Stichprobenartige Überprüfung abgeschlossener Jobs und Abgleich, ob das für den Benutzer sichtbare Asset, der Nutzungsdatensatz und der gespeicherte Task-Datensatz übereinstimmen.

API-Referenz

ThemaReferenz
FehlerbehandlungFehlerbehandlung
RatenlimitsRatenlimits
Abrechnung & PreiseAbrechnung & Preise
Get API Key UsageAPI-Schlüssel-Nutzung abrufen
Get Task StatusAufgabenstatus abrufen

Auf dieser Seite