Errori e limiti dell'API

Questa pagina documenta il formato degli errori, l'elenco completo dei codici di risposta, i limiti di richiesta e come l'utilizzo del piano influisce sulla traduzione.

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 è abilitata per il tuo sito.
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.
LIMITE_PIANO_RAGGIUNTO	403	La tua quota di parole del piano è esaurita.
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.

Limiti di richiesta

Limite	Valore
Corpo massimo della richiesta	5 MB
Stringhe massime per richiesta	500 (endpoint stringhe)
Metodi consentiti	GET, POST, OPTIONS

Se il corpo supera i 5 MB ricevi REQUEST_TOO_LARGE (413). Per pagine o set di stringhe di grandi dimensioni, suddividi il lavoro su più richieste.

Corpi delle richieste compressi

Il Translator accetta corpi delle richieste compressi con gzip. Imposta l'intestazione Content-Encoding su gzip e invia il JSON compresso; il corpo viene decompresso prima dell'analisi. Questo è utile per grandi documenti HTML che si avvicinano al limite 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 consuma la quota di parole del tuo piano, condivisa tra gli endpoint HTML e stringhe. L'utilizzo viene applicato per richiesta anziché rifiutando l'intera chiamata:

• Se la tua quota è esaurita prima che arrivi una richiesta, la richiesta fallisce con PLAN_LIMIT_REACHED (403).
• Se la quota si esaurisce a metà di una richiesta, Universally traduce il più possibile, restituisce una risposta di successo e segnala la carenza nei metadati.

Due campi di metadati descrivono questo:

Campo	Significato
limiteRaggiunto	true quando la quota di parole è stata raggiunta durante la richiesta.
stringheSaltate	Il numero di stringhe rimaste nella lingua di origine perché è stato raggiunto il limite.

Quando limitReached è true, tratta la risposta come parziale: il contenuto tradotto viene restituito dove possibile e le stringhe non tradotte tornano al loro testo originale. Aggiorna il tuo piano per aumentare la quota.

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.