AI Glot websiteOpen AI Glot
REST-APIFehler

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.

Example error
{
  "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

StatusBedeutungMaßnahme
400Fehlerhafte Anfrage oder unbekanntes FeldAnfrage korrigieren
401Anmeldedaten fehlen, sind ungültig, abgelaufen oder widerrufenErsetzen oder erneuern
403Authentifiziert, aber nicht berechtigtErforderlichen Scope oder erforderliche Funktion freigeben
404Ressource nicht vorhanden oder außerhalb dieses WorkspaceID und Workspace überprüfen
409Aktueller Zustand steht im Konflikt mit der AnfrageRessource abrufen und dann entscheiden
413Anfragekörper zu großKleineren Anfragekörper senden
422Wohlgeformter, aber ungültiger WertDen angegebenen Wert korrigieren
429Ratenbegrenzung erreichtAuf Retry-After warten
500/503AI Glot ist fehlgeschlagen oder vorübergehend nicht verfügbarMit 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:

JSON
"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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.