Riferimento API completo: developer.universally.com contiene la specifica live sia per la Translator API che per la Platform API, con ogni campo, codice di stato ed esempio di risposta. Questa pagina copre ciò che vale la pena sapere al riguardo.
Ogni risposta utilizza lo stesso wrapper, quindi un client si basa sul campo code anziché solo sullo stato HTTP.
Envelope della risposta
Ogni risposta, di successo o di errore, utilizza lo stesso envelope JSON:
{
"success": false,
"data": null,
"message": "Invalid source URL format.",
"code": "TRANSLATION_INVALID_SOURCE_URL"
}
In caso di errore, success è false e data è null. Ramifica sul campo code anziché sul message leggibile dall'uomo, che potrebbe cambiare.
Codici di errore
| Codice | HTTP | Significato |
|---|---|---|
CHIAVE_API_MANCANTE |
401 | Nessun header X-API-Key è stato fornito. |
CHIAVE_API_FORMATO_NON_VALIDO |
401 | La chiave non ha un formato riconosciuto. |
CHIAVE_API_NON_CORRETTA |
401 | La chiave non è stata analizzata correttamente. |
CHIAVE_API_NON_VALIDA |
401 | La chiave è ben formattata ma non riconosciuta. |
API_KEY_PROGETTO_INCOMPLETO |
500 | Il sito associato a questa chiave è configurato in modo errato. Contatta il supporto. |
PROGETTO_NON_TROVATO |
404 | Nessun sito corrisponde a questa chiave. |
PROGETTO_ELIMINATO |
404 | Il sito è stato eliminato e non è più accessibile. |
URL_SORGENTE_TRADUZIONE_NON_VALIDO |
400 | sourceUrl non è un URL valido. |
URL_SORGENTE_TRADUZIONE_DOMINIO_DIVERSO |
403 | sourceUrl non corrisponde al dominio del tuo sito. |
TRADUZIONE_STESSA_LINGUA |
400 | La lingua di destinazione è uguale alla lingua di origine. |
LINGUA_TARGET_TRADUZIONE_NON_CONSENTITA |
403 | La lingua di destinazione non è configurata per il tuo sito oppure hai inviato un codice regione dove era richiesto un codice variante. |
TRADUZIONE_NESSUNA_LINGUA_CONFIGURATA |
400 | Nessuna lingua di destinazione è configurata per il sito. |
SERVIZIO_TRADUZIONE_NON_DISPONIBILE |
503 | Il servizio di traduzione non è temporaneamente disponibile. Riprova con backoff. |
ERRORE_SERVIZIO_TRADUZIONE |
500 | Il servizio di traduzione non è riuscito a elaborare la richiesta. |
NESSUN_CONTENUTO_TRADUCIBILE |
400 | Nessun contenuto traducibile trovato nell'HTML. |
ERRORE_VALIDAZIONE |
400 | Il corpo della richiesta non ha superato la validazione dello schema. |
JSON_NON_VALIDO |
400 | Il corpo della richiesta non è JSON valido. |
ERRORE_DECOMPRESSIONE |
400 | Un corpo gzip non è stato decompresso. |
RICHIESTA_TROPPO_GRANDE |
413 | Il corpo della richiesta supera i 5 MB. |
NON_TROVATO |
404 | Percorso sconosciuto. |
ERRORE_INTERNO_DEL_SERVER |
500 | Errore imprevisto del server. È sicuro riprovare con un backoff. |
Limiti di richiesta
| Limite | Valore |
|---|---|
| Corpo massimo della richiesta | 5 MB |
| Stringhe massime per richiesta | 500 (endpoint stringhe) |
| Metodi consentiti | GET, POST, OPTIONS |
Il limite di 5 MB si applica ai byte inviati, quindi un corpo gzippato viene misurato compresso. Se viene superato, ricevi REQUEST_TOO_LARGE (413). Per pagine o set di stringhe di grandi dimensioni, comprimi il corpo o suddividi il lavoro in più richieste.
Corpi delle richieste compressi
Il Translator accetta corpi di richiesta compressi gzip. Imposta l'intestazione Content-Encoding su gzip e invia il JSON compresso; il corpo viene decompresso prima dell'analisi. Poiché il limite di dimensioni conta i byte inviati, la compressione consente di elaborare un documento più grande di 5 MB.
Content-Type: application/json
Content-Encoding: gzip
Se la decompressione fallisce, la risposta è DECOMPRESSION_ERROR (400).
Richieste cross-origin
Il Translator restituisce intestazioni CORS permissive, consentendo richieste da qualsiasi origine con le intestazioni Content-Type, X-API-Key e Content-Encoding. Anche così, le richieste trasportano la tua chiave API e dovrebbero essere inviate lato server. Vedi Autenticazione.
Utilizzo del piano e traduzioni parziali
La traduzione riduce il conteggio totale delle parole del tuo piano, condiviso tra gli endpoint HTML e stringhe.
Superare il limite non è un errore. Non esiste un codice di stato per questo: un'area di lavoro oltre il limite riceve comunque un 200, con la carenza segnalata nei metadati. Il limite viene controllato una sola volta, all'arrivo della richiesta, quindi una richiesta che inizia sotto il limite completa tutto ciò che necessita, anche se ciò la porta oltre il totale.
| Campo | Significato |
|---|---|
limiteRaggiunto |
true se l'area di lavoro era già al limite o oltre il suo totale di parole all'arrivo della richiesta. |
stringheSaltate |
Il numero di stringhe lasciate non tradotte a causa di ciò. |
Quando limitReached è true, tratta la risposta come parziale. Tutto ciò che è già stato tradotto viene ancora restituito dallo storage; tutto ciò che avrebbe richiesto una nuova traduzione non viene restituito. Sull'endpoint HTML quel testo rimane nella lingua di origine nel documento restituito. Sull'endpoint delle stringhe quelle chiavi sono assenti dalla mappa translations, quindi utilizza il tuo testo sorgente come fallback per qualsiasi chiave che non ricevi indietro. Vedi Traduci stringhe.
Aumenta il totale con un add-on di parole o un piano più grande. Vedi Limiti di utilizzo.
Tentativi
Per errori transitori (TRANSLATION_SERVICE_UNAVAILABLE a 503, o qualsiasi 5xx), ritenta con backoff esponenziale. Le traduzioni vengono memorizzate nella cache, quindi le richieste ritentate che hanno avuto parzialmente successo in precedenza riutilizzano il lavoro esistente e traducono solo ciò che manca ancora. Non ritentare errori 4xx; indicano un problema con la richiesta che non si risolverà da solo.