Fehler
Behandeln Sie Fehler der AI Glot API mithilfe stabiler Fehlercodes, Request-IDs, Hinweisen zu Wiederholungsversuchen und Erläuterungen mit Ankern für alle dokumentierten Fehler.
Jeder API-Fehler folgt demselben Schema. Verwenden Sie error.code zur Verzweigung, niemals die menschenlesbare Meldung.
{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This credential is missing the batches:write scope.",
"docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
},
"request_id": "req_example"
}Statuscodes
| Status | Bedeutung | Maßnahme |
|---|---|---|
| 400 | Fehlerhafte Anfrage oder unbekanntes Feld | Anfrage korrigieren |
| 401 | Anmeldedaten fehlen, sind ungültig, abgelaufen oder widerrufen | Ersetzen oder erneuern |
| 403 | Authentifiziert, aber nicht berechtigt | Erforderlichen Scope oder erforderliche Funktion freigeben |
| 404 | Ressource nicht vorhanden oder außerhalb dieses Workspace | ID und Workspace überprüfen |
| 409 | Aktueller Zustand steht im Konflikt mit der Anfrage | Ressource abrufen und dann entscheiden |
| 413 | Anfragekörper zu groß | Kleineren Anfragekörper senden |
| 422 | Wohlgeformter, aber ungültiger Wert | Den angegebenen Wert korrigieren |
| 429 | Ratenbegrenzung erreicht | Auf Retry-After warten |
| 500/503 | AI Glot ist fehlgeschlagen oder vorübergehend nicht verfügbar | Mit exponentiellem Backoff erneut versuchen |
Authentifizierungs- und Berechtigungscodes
authentication_required
Es wurde kein Bearer-Token übermittelt. Fügen Sie den Authorization-Header hinzu.
invalid_api_key
Der Schlüssel ist fehlerhaft oder unbekannt. Prüfen Sie, ob der vollständige Wert aig_live_… kopiert wurde.
api_key_expired
Der Schlüssel hat sein festgelegtes Ablaufdatum erreicht. Erstellen oder verwenden Sie einen Ersatzschlüssel.
api_key_revoked
Ein Admin hat diesen Schlüssel widerrufen oder rotiert. Aktualisieren Sie die Integration mit aktiven Anmeldedaten.
insufficient_scope
Die Anmeldedaten wurden authentifiziert, verfügen jedoch nicht über den für diesen Vorgang erforderlichen Scope.
feature_not_available
Der Workspace-Tarif oder die aktuelle Plattformversion umfasst die angeforderte Funktion nicht.
admin_required
Nur ein Workspace-Admin darf diesen Vorgang ausführen.
Anfragecodes
invalid_request
Die Anfrage lässt sich nicht parsen oder entspricht nicht den Vorgaben des Endpunkts.
unknown_field
Eine Eigenschaft im JSON-Anfragekörper ist nicht bekannt. Korrigieren Sie die Schreibweise, statt die Validierung zu entfernen. Unbekannte Abfrageparameter lösen diesen Fehler nicht aus, sondern werden ignoriert. Ein falsch geschriebener Filter führt daher zu einer ungefilterten Antwort mit Status 200.
invalid_parameter
Ein Parameter hat den falschen Typ, liegt außerhalb des zulässigen Bereichs oder weist ein ungültiges Format auf.
invalid_cursor
Der Cursor für die Paginierung ist ungültig. Verwenden Sie next_cursor exakt so, wie er zurückgegeben wurde.
request_too_large
Der Anfragekörper überschreitet das feste Limit des Endpunkts.
Ressourcen- und Statuscodes
batch_not_found
Es ist keine sichtbare Übersetzung mit dieser ID vorhanden. Ressourcen in einem anderen Workspace führen absichtlich zum selben Fehler.
glossary_not_found
Für dieses Sprachpaar ist kein Glossar vorhanden.
resource_not_found
Die angeforderte Ressource oder Route existiert nicht.
glossary_already_exists
Für dieses Sprachpaar ist bereits ein Glossar vorhanden. Aktualisieren Sie es, statt ein weiteres zu erstellen.
result_not_ready
Die Übersetzung ist noch nicht abgeschlossen. Daher kann noch kein Ergebnis heruntergeladen werden.
batch_not_editable
Der aktuelle Status der Übersetzung lässt die angeforderte administrative Änderung nicht zu.
idempotency_key_reused
Der Idempotency-Key wurde bereits für eine andere Anfrage verwendet (andere Datei, anderer Name oder andere Anweisung). Senden Sie dieselbe Anfrage, um sie zu wiederholen, oder einen neuen Schlüssel für neue Arbeit. Siehe Eine Übersetzung erstellen.
Datei- und Formatcodes
unsupported_format
AI Glot unterstützt diese Dateiendung nicht. Eine vollständige Liste der Formate und Dateiendungen finden Sie unter Dateien und Formate.
file_too_large
Die Datei überschreitet die Größenbegrenzung für ihr Format. Die Limits gelten je Format und nicht allgemein (60 MB für CSV, 4 MB für einen PO-Katalog). Eine Dateigröße, die bei einer Endung zulässig ist, kann bei einer anderen abgelehnt werden.
file_fetch_failed
file_url konnte nicht abgerufen werden. Die URL muss HTTPS verwenden und direkt zum endgültigen Ziel führen. Weiterleitungen werden nicht verfolgt. Daher schlagen hier verkürzte Links oder Links fehl, die nach einer Signierung weiterleiten.
file_retention_expired
Die Aufbewahrungsfrist der hochgeladenen Datei ist abgelaufen und sie wird nicht mehr gespeichert. Erstellen Sie die Übersetzung erneut aus der Quelldatei.
file_expired
Die Datei, auf der diese Übersetzung basiert, ist nicht mehr verfügbar. Der Vorgang kann daher nicht fortgesetzt werden.
result_too_large
Die fertige Übersetzung überschreitet die zulässige Größe für die Rückgabe. Teilen Sie die Quelldatei auf und übersetzen Sie die Teile einzeln.
Tarif- und Freigabecodes
plan_invalid
Die Anweisung oder Verfeinerung ließ sich nicht in einen nutzbaren Plan umsetzen. Es wurden keine Kosten berechnet. Wenn die Ursache bekannt ist, erklärt die Meldung den Grund: Die Anweisung trifft auf nichts in der Datei zu, verlangt eine Änderung an einer Stelle, die in der Datei nicht bearbeitet werden kann, oder der Plan konnte diesmal nicht erstellt werden (senden Sie dieselbe Anweisung erneut). Andernfalls formulieren Sie die Anweisung um. Es ist zuverlässiger, die zu übersetzenden Felder oder Spalten zu benennen, als sie nur zu beschreiben.
plan_changed
Der übermittelte Wert für expected_plan_revision stimmt nicht mit dem aktuellen überprüfbaren Plan überein oder lässt sich nicht verifizieren. Durch diese Freigabe wurden keine neuen Arbeiten gestartet. Rufen Sie den Batch erneut ab und prüfen Sie den aktuellen Umfang, die Ausschlüsse und die berechneten Kosten. Entscheiden Sie anschließend, ob Sie die Freigabe mit der neuen Revision erteilen möchten. Wiederholen Sie die Freigabe mit der alten Revision nicht ungeprüft.
no_plan_yet
Die Freigabe wurde angefordert, bevor ein Plan vorlag. Rufen Sie zuerst POST /v1/batches/{batch_id}/plan auf. Diese Prüfung verhindert, dass eine Integration einem Workspace eine Übersetzung in Rechnung stellt, die niemand beschrieben hat.
batch_not_awaiting_approval
Die Übersetzung befindet sich nicht in einem Status, in dem eine Freigabe möglich ist. Meist läuft sie bereits oder ist schon abgeschlossen. Rufen Sie stattdessen GET /v1/batches/{batch_id} wiederholt ab, anstatt sie erneut freizugeben.
insufficient_credits
Das Guthaben des Workspace reicht nicht aus, um die berechneten Kosten des Plans zu decken (HTTP 402). Es wird nichts reserviert. Sobald Guthaben hinzugefügt wurde, kann die Übersetzung weiterhin freigegeben werden.
Der Fehler enthält ein payment-Objekt, sowohl in der REST API als auch im MCP-Tool approve_translation:
"payment": {
"credits_needed": 30000,
"credit_balance": 5000,
"credits_missing": 25000,
"credits_to_buy": 25000,
"price_eur": 25,
"payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
"plans": [
{ "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
{ "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
]
}credits_to_buy gibt den kleinsten Kaufbetrag an, der die Differenz abdeckt (der Mindestkaufbetrag gilt). payment_url öffnet diese Übersetzung in AI Glot und zeigt sofort das Kaufdialogfeld an: den genauen Betrag, die Guthabenpakete und Tarife sowie die kostenlose Probeübersetzung, sofern der Workspace dafür infrage kommt. Der Link funktioniert nur für angemeldete Mitglieder des Workspace und kann daher bedenkenlos angezeigt werden. plans enthält die Monatstarife, die pro Guthabeneinheit günstiger sind, wenn regelmäßig übersetzt wird. Auf derselben Seite werden sie unter dem einmaligen Kauf angezeigt.
Ein Agent sollte den Nutzer fragen, bevor er den Link anbietet, niemals in seinem Namen bezahlen und nach der Zahlung das Guthaben mit GET /v1/account überprüfen. Nach Bestätigung durch den Nutzer kann die Übersetzung erneut freigegeben werden. Der Nutzer kann die Übersetzung auch direkt auf dieser Seite starten.
Sprach- und Glossarcodes
language_not_supported
Das Sprach-Tag gehört nicht zum unterstützten Katalog. Rufen Sie GET /v1/languages ab.
invalid_language_pair
Die Kennung des Sprachpaars lässt sich nicht in zwei unterstützte BCP-47-Tags aufteilen.
glossary_term_limit_reached
Die Anzahl der Einträge würde das im Workspace-Tarif enthaltene Limit überschreiten. Die Aktualisierung erfolgt atomar. Es wurde nichts geändert.
glossary_limit_reached
Der Workspace hat die für den aktuellen Tarif zulässige Anzahl an Glossaren erreicht.
invalid_glossary_terms
Mindestens ein Glossareintrag ist leer, unvollständig oder anderweitig ungültig.
Servicecodes
rate_limited
Die Anmeldedaten haben das Ratenlimit für ein Zeitfenster überschritten. Warten Sie Retry-After ab und versuchen Sie es dann mit zufälligem Jitter erneut.
internal_error
Bei AI Glot ist ein unerwarteter Fehler aufgetreten. Versuchen Sie es mit Backoff erneut und bewahren Sie die request_id auf.
service_unavailable
Ein benötigter Dienst ist vorübergehend nicht verfügbar. Versuchen Sie es mit Backoff erneut.