Fehler und Statuscodes

API-Problemantworten verstehen, fehlgeschlagene Anfragen beheben und HTTP-Fehler von Fehlern bei der Übersetzungsverarbeitung unterscheiden.

Sehen Sie sich den HTTP-Status an, bevor Sie eine erfolgreiche Antwort dekodieren. Die API unter https://api.lingo.dev/v2 meldet Fehler als JSON-Problemdetails. Auch ein erfolgreich abgerufener Auftrag kann fehlgeschlagene Aufgaben enthalten. Sehen Sie sich daher zusätzlich den Auftragsstatus an.

Eine Problemantwort lesen #

Problemantworten verwenden Content-Type: application/problem+json. Häufige Felder sind type, title, status und detail. Benannte Probleme enthalten außerdem Felder, die die betroffene Ressource oder die erforderliche Korrektur angeben.

Dieses Beispiel zeigt einen nicht gefundenen Lokalisierungsauftrag:

json
{
  "type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
  "title": "Localization job not found",
  "status": 404,
  "detail": "Localization job lfr_example not found.",
  "id": "lfr_example"
}

Die URI in type identifiziert das Problem. Im API-Fehlerkatalog finden Sie die Felder und Endpunkte für jedes benannte Problem. Behalten Sie die zurückgegebene URI unverändert bei, wenn Sie einen Fehler speichern oder klassifizieren.

Eine ungültige Anfrage korrigieren #

Besteht eine Anfrage die Validierung nicht, gibt die API 400 Bad Request mit type: "about:blank" zurück. Sind Validierungsdetails verfügbar, listet errors für jedes Problem path und message auf:

json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "path": ["payload", "documents", 0, "source"],
      "message": "Expected a JSON object"
    }
  ]
}

Der Pfad beginnt mit dem Teil der Anfrage, der validiert wird, etwa payload. Darauf folgen Eigenschaftsnamen und nullbasierte Array-Indizes. Dieses Beispiel verweist auf source im ersten documents-Eintrag im Anfragekörper. Korrigieren Sie den angegebenen Wert anhand des Endpunktschemas, bevor Sie die Anfrage erneut senden. about:blank ist ein generischer Problemtyp und hat daher keinen Eintrag im Katalog benannter Fehler.

Die passende Fehlerbehebung wählen #

HTTP-StatusTypische UrsacheNächster Schritt
400Die Anfrage entspricht nicht dem Schema der Route.Korrigieren Sie Pfad, Abfrageparameter, Header oder Anfragekörper anhand der gemeldeten Validierungsdetails.
401Fehlende, ungültige oder abgelaufene Zugangsdaten.Laden Sie den vorgesehenen Schlüssel oder erneuern Sie die Benutzersitzung.
402Unzureichendes Guthaben, im Tarif nicht verfügbare Funktionen oder ein nach einer RBAC-Herabstufung deaktivierter Dienstschlüssel.Lesen Sie die angegebene Bedingung und erfüllen Sie die entsprechende Konto- oder Tarifanforderung.
403Eine Berechtigung oder eine erforderliche Benutzeridentität fehlt, oder es besteht eine Einschränkung durch ein Feature-Flag.Kontrollieren Sie den Aufrufer und die Zugriffsanforderungen der Operation.
404Die Ressource existiert nicht oder ist für diesen Aufrufer nicht sichtbar.Kontrollieren Sie die Kennung, die Organisation und die Ressourcenberechtigungen.
409Die Operation steht im Konflikt mit dem Zustand der Ressource.Rufen Sie die aktuelle Ressource ab. Laden Sie je nach Hinweis fehlende Artefakte hoch, schließen Sie laufende Aufgaben ab oder aktualisieren Sie eine abgeschlossene Prüfung.
413Ein Upload oder Anfragekörper überschreitet die Größenbegrenzung.Verkleinern Sie die Eingabe oder teilen Sie die Aufgaben auf. Pro Artefakt-Upload sind bis zu 25 MiB zulässig.
422Die Anfrage ist strukturell gültig, verstößt aber gegen die Vorgaben einer Operation.Beheben Sie das angegebene Problem, etwa eine ungültige Bearbeitung im Rahmen einer Prüfung oder einen wiederverwendeten Idempotenzschlüssel.
429Ein Nutzungs- oder Operationslimit wurde erreicht.Halten Sie den in der Problemantwort angegebenen Zeitpunkt für einen erneuten Versuch ein. Ist keiner angegeben, sehen Sie vor einem erneuten Versuch das Kontolimit nach.
5xxEin Server oder eine Abhängigkeit konnte die Anfrage nicht abschließen.Bewahren Sie die Ressourcen- und Anfrage-IDs auf. Wiederholen Sie die Anfrage nur gemäß der Semantik der Operation.

detail erläutert den konkreten Fehler. Der Status allein reicht für eine vollständige Klassifizierung nicht aus. Antworten von einem Proxy oder bei einem Netzwerkfehler enthalten möglicherweise keinen Antwortkörper mit Problemdetails. Bewahren Sie zur Diagnose den HTTP-Status und den lesbaren Antworttext auf, ohne geheime Daten zu protokollieren.

Eine Lokalisierungsanfrage erneut senden #

Speichern Sie Idempotency-Key der Erstellungsanfrage, bevor Sie diese senden. Geht die Antwort verloren, wiederholen Sie dieselbe Erstellungsanfrage mit diesem Schlüssel, um den ursprünglichen Auftrag abzurufen. Ein neuer Schlüssel erzeugt neue Aufgaben.

Speichern Sie nach der Erstellung die Auftrags-ID. Rufen Sie diesen Auftrag ab, bevor Sie entscheiden, ob Sie einen weiteren erstellen. Uploads verwenden exakt die Bytes, die durch ihre SHA-256-Adresse bezeichnet werden. Schließen Sie alle fehlenden Uploads vor dem Start ab. Auch bei einer Wiederholung bezieht sich /start auf denselben Auftrag.

Die Zulassungskontrollen erfolgen beim Start. Bei DailyTokenLimitReached oder unzureichendem Guthaben bleibt ein ausstehender Auftrag erhalten und kann später gestartet werden, sobald das Kontoproblem behoben ist. Das wiederholte Erstellen neuer Aufträge behebt kein Kontolimit.

Anfragefehler von Fehlern bei der Verarbeitung unterscheiden #

Ein HTTP-Status 200 von GET /v2/localization/jobs/:id bedeutet, dass der Auftrag abgerufen wurde. Sein status._tag kann dennoch Failed sein. Sehen Sie sich status.message, den Status jedes Ziels sowie die Warnungen und Fehler der einzelnen Phasen an.

Abgeschlossene Ziele bleiben zum Download verfügbar, auch wenn ein anderes Ziel fehlschlägt. Behalten Sie diese und senden Sie nach Behebung der Ursache nur die Aufgaben erneut, die neu generiert werden müssen. Eine Zeitüberschreitung beim clientseitigen Statusabruf bricht den Auftrag nicht ab.

Für die Bereitstellung gibt es eigene Ergebnisse und Schritte zur Fehlerbehebung je Typ. Für Prüfungsentscheidungen gibt es eigene Fehler bei abgeschlossenen Prüfungen und ungültigen Bearbeitungen. Orientieren Sie sich bei der Fehlerbehebung am Zustand dieser Ressourcen, statt bei jedem Fehler den ursprünglichen Schreibvorgang zu wiederholen.