Vollständige API-Referenz: developer.universally.com enthält die Live-Spezifikation für die Translator API und die Platform API mit jedem Feld, Statuscode und Antwortbeispiel. Diese Seite behandelt, was man darüber wissen sollte.
Jede Antwort verwendet dieselbe Hülle, sodass ein Client auf das Feld code reagiert und nicht nur auf den HTTP-Status.
Antwort-Envelope
Jede Antwort, ob erfolgreich oder fehlerhaft, verwendet dieselbe JSON-Envelope:
{
"success": false,
"data": null,
"message": "Invalid source URL format.",
"code": "TRANSLATION_INVALID_SOURCE_URL"
}
Bei einem Fehler ist success false und data ist null. Verzweigen Sie anhand des Feldes code und nicht anhand der menschenlesbaren message, die sich ändern kann.
Fehlercodes
| Code | HTTP | Bedeutung |
|---|---|---|
API_SCHLÜSSEL_FEHLT |
401 | Es wurde kein X-API-Key-Header angegeben. |
API_SCHLÜSSEL_UNGÜLTIGES_FORMAT |
401 | Der Schlüssel hat kein anerkanntes Format. |
API_SCHLÜSSEL_FEHLERHAFT |
401 | Der Schlüssel konnte nicht analysiert werden. |
API_SCHLÜSSEL_UNGÜLTIG |
401 | Der Schlüssel ist korrekt formatiert, wird aber nicht erkannt. |
API_SCHLÜSSEL_PROJEKT_UNVOLLSTÄNDIG |
500 | Die diesem Schlüssel zugeordnete Website ist falsch konfiguriert. Kontaktieren Sie den Support. |
PROJEKT_NICHT_GEFUNDEN |
404 | Keine Website entspricht diesem Schlüssel. |
PROJEKT_IST_GELÖSCHT |
404 | Die Website wurde gelöscht und ist nicht mehr zugänglich. |
ÜBERSETZUNG_UNGÜLTIGE_QUELL_URL |
400 | sourceUrl ist keine gültige URL. |
ÜBERSETZUNG_QUELL_URL_DOMAIN_NICHT_ÜBEREINSTIMMEND |
403 | sourceUrl stimmt nicht mit der Domain Ihrer Website überein. |
ÜBERSETZUNG_GLEICHE_SPRACHE |
400 | Die Zielsprache entspricht der Quellsprache. |
ÜBERSETZUNG_ZIELSPRACHE_NICHT_ERLAUBT |
403 | Die Zielsprache ist für Ihre Website nicht konfiguriert, oder Sie haben einen Regionscode gesendet, bei dem ein Variantencode erforderlich ist. |
ÜBERSETZUNG_KEINE_SPRACHEN_KONFIGURIERT |
400 | Für die Website sind keine Zielsprachen konfiguriert. |
ÜBERSETZUNGSDIENST_NICHT_VERFÜGBAR |
503 | Der Übersetzungsdienst ist vorübergehend nicht verfügbar. Versuchen Sie es später erneut. |
ÜBERSETZUNGSDIENST_FEHLGESCHLAGEN |
500 | Der Übersetzungsdienst konnte die Anfrage nicht verarbeiten. |
KEIN_ÜBERSETZBARER_INHALT |
400 | Es wurden keine übersetzbaren Inhalte im HTML gefunden. |
VALIDIERUNGSFEHLER |
400 | Der Anfragekörper hat die Schema-Validierung nicht bestanden. |
UNGÜLTIGES_JSON |
400 | Der Anfragekörper ist kein gültiges JSON. |
DEKOMPRESSIONSFEHLER |
400 | Ein Gzip-Körper konnte nicht dekomprimiert werden. |
ANFRAGE_ZU_GROSS |
413 | Der Anfragekörper überschreitet 5 MB. |
NICHT_GEFUNDEN |
404 | Unbekannte Route. |
INTERNER_SERVERFEHLER |
500 | Unerwarteter Serverfehler. Ein erneuter Versuch mit Backoff ist sicher. |
Anfragelimits
| Limit | Wert |
|---|---|
| Maximaler Anfragekörper | 5 MB |
| Maximale Zeichenketten pro Anfrage | 500 (Zeichenketten-Endpunkt) |
| Zulässige Methoden | GET, POST, OPTIONS |
Das 5-MB-Limit gilt für die von Ihnen gesendeten Bytes, sodass ein gzip-komprimierter Body komprimiert gemessen wird. Wenn es überschritten wird, erhalten Sie REQUEST_TOO_LARGE (413). Bei großen Seiten oder großen String-Sets komprimieren Sie den Body oder teilen Sie die Arbeit auf mehrere Anfragen auf.
Komprimierte Anfragekörper
Der Translator akzeptiert gzip-komprimierte Anforderungs-Bodies. Setzen Sie den Header Content-Encoding auf gzip und senden Sie das komprimierte JSON; der Body wird vor dem Parsen dekomprimiert. Da das Größenlimit die von Ihnen gesendeten Bytes zählt, ermöglicht die Komprimierung, dass ein Dokument, das um ein Vielfaches größer als 5 MB ist, durchgeht.
Content-Type: application/json
Content-Encoding: gzip
Wenn die Dekomprimierung fehlschlägt, ist die Antwort DECOMPRESSION_ERROR (400).
Anfragen von Drittanbietern
Der Translator gibt permissive CORS-Header zurück, die Anfragen von jedem Ursprung mit den Headern Content-Type, X-API-Key und Content-Encoding zulassen. Dennoch enthalten Anfragen Ihren API-Schlüssel und sollten serverseitig gesendet werden. Siehe Authentifizierung.
Plan-Nutzung und Teilübersetzungen
Übersetzung reduziert die Wortanzahl Ihres Plans, die für die HTML- und String-Endpunkte gemeinsam genutzt wird.
Das Überschreiten des Limits ist kein Fehler. Es gibt keinen Statuscode dafür: Ein Workspace, der das Limit bereits überschritten hat, erhält trotzdem eine 200, wobei die Unterschreitung in den Metadaten gemeldet wird. Das Limit wird einmal geprüft, wenn die Anfrage eintrifft. Eine Anfrage, die unter dem Limit beginnt, schließt alles ab, was sie benötigt, auch wenn sie dadurch das Gesamtlimit überschreitet.
| Feld | Bedeutung |
|---|---|
limitReached |
true, wenn der Workspace bei Ankunft der Anfrage bereits sein Wortlimit erreicht hatte oder darüber lag. |
skippedStrings |
Die Anzahl der Strings, die aufgrund dessen nicht übersetzt wurden. |
Wenn limitReached auf true gesetzt ist, behandeln Sie die Antwort als teilweise. Alles, was bereits übersetzt wurde, wird weiterhin aus dem Speicher zurückgegeben; alles, was eine neue Übersetzung erfordert hätte, nicht. Auf dem HTML-Endpunkt verbleibt der Text in der Quellsprache im zurückgegebenen Dokument. Auf dem String-Endpunkt fehlen diese Schlüssel in der translations-Map, sodass Sie für jeden Schlüssel, den Sie nicht zurückerhalten, auf Ihren eigenen Quelltext zurückgreifen. Siehe Strings übersetzen.
Erhöhen Sie das Limit mit einem Wort-Add-on oder einem größeren Plan. Siehe Nutzungsbeschränkungen.
Wiederholungsversuche
Bei transienten Fehlern (TRANSLATION_SERVICE_UNAVAILABLE bei 503 oder jeder 5xx) versuchen Sie es mit exponentiellem Backoff erneut. Übersetzungen werden zwischengespeichert, sodass wiederholte Anfragen, die zuvor teilweise erfolgreich waren, vorhandene Arbeiten wiederverwenden und nur das übersetzen, was noch fehlt. Versuchen Sie nicht, 4xx-Fehler zu wiederholen; sie weisen auf ein Problem mit der Anfrage hin, das sich nicht von selbst löst.