Erros e Limites da API

Esta página documenta o formato de erro, a lista completa de códigos de resposta, os limites de solicitação e como o uso do plano afeta a tradução.

Envelope de resposta

Toda resposta, de sucesso ou erro, usa o mesmo envelope JSON:

{
  "success": false,
  "data": null,
  "message": "Invalid source URL format.",
  "code": "TRANSLATION_INVALID_SOURCE_URL"
}

Em caso de erro, success é false e data é null. Ramifique com base no campo code em vez da message legível por humanos, que pode mudar.

Códigos de erro

Código	HTTP	Significado
CHAVE_DA_API_AUSENTE	401	Nenhum cabeçalho X-API-Key foi fornecido.
CHAVE_DA_API_FORMATO_INVÁLIDO	401	A chave não tem um formato reconhecido.
CHAVE_DA_API_MAL_FORMADA	401	A chave não pôde ser analisada.
CHAVE_DA_API_INVÁLIDA	401	A chave está bem formatada, mas não é reconhecida.
CHAVE_DA_API_PROJETO_INCOMPLETO	500	O site associado a esta chave está mal configurado. Entre em contato com o suporte.
PROJETO_NÃO_ENCONTRADO	404	Nenhum site corresponde a esta chave.
PROJETO_FOI_EXCLUÍDO	404	O site foi excluído e não está mais acessível.
URL_DE_ORIGEM_DE_TRADUÇÃO_INVÁLIDA	400	sourceUrl não é uma URL válida.
URL_DE_ORIGEM_DE_TRADUÇÃO_DOMÍNIO_INCOMPATÍVEL	403	sourceUrl não corresponde ao domínio do seu site.
IDIOMA_DE_ORIGEM_DE_TRADUÇÃO_IGUAL	400	O idioma de destino é igual ao idioma de origem.
IDIOMA_DE_DESTINO_DE_TRADUÇÃO_NÃO_PERMITIDO	403	O idioma de destino não está habilitado para o seu site.
NENHUM_IDIOMA_DE_TRADUÇÃO_CONFIGURADO	400	Nenhum idioma de destino está configurado para o site.
SERVIÇO_DE_TRADUÇÃO_INDISPONÍVEL	503	O serviço de tradução está temporariamente indisponível. Tente novamente com backoff.
FALHA_NO_SERVIÇO_DE_TRADUÇÃO	500	O serviço de tradução falhou ao processar a solicitação.
NENHUM_CONTEÚDO_TRADUZÍVEL	400	Nenhum conteúdo traduzível foi encontrado no HTML.
LIMITE_DO_PLANO_ATINGIDO	403	A cota de palavras do seu plano foi esgotada.
ERRO_DE_VALIDAÇÃO	400	O corpo da solicitação falhou na validação do esquema.
JSON_INVÁLIDO	400	O corpo da solicitação não é um JSON válido.
ERRO_DE_DESCOMPACTAÇÃO	400	Um corpo gzip não pôde ser descompactado.
REQUISIÇÃO_MUITO_GRANDE	413	O corpo da solicitação excede 5 MB.
NÃO_ENCONTRADO	404	Rota desconhecida.

Limites de solicitação

Limite	Valor
Corpo máximo da solicitação	5 MB
Máximo de strings por solicitação	500 (endpoint de strings)
Métodos permitidos	GET, POST, OPTIONS

Se o corpo exceder 5 MB, você receberá REQUEST_TOO_LARGE (413). Para páginas grandes ou grandes conjuntos de strings, divida o trabalho em várias solicitações.

Corpos de solicitação compactados

O Translator aceita corpos de solicitação compactados com gzip. Defina o cabeçalho Content-Encoding como gzip e envie o JSON compactado; o corpo é descompactado antes da análise. Isso é útil para documentos HTML grandes que se aproximam do limite de 5 MB.

Content-Type: application/json
Content-Encoding: gzip

Se a descompactação falhar, a resposta será DECOMPRESSION_ERROR (400).

Solicitações cross-origin

O Translator retorna cabeçalhos CORS permissivos, permitindo solicitações de qualquer origem com os cabeçalhos Content-Type, X-API-Key e Content-Encoding. Mesmo assim, as solicitações carregam sua chave de API e devem ser enviadas do lado do servidor. Veja Autenticação.

Uso do plano e traduções parciais

A tradução consome a cota de palavras do seu plano, compartilhada entre os endpoints HTML e de strings. O uso é aplicado por solicitação, em vez de rejeitar a chamada inteira:

• Se sua cota se esgotar antes da chegada de uma solicitação, a solicitação falhará com PLAN_LIMIT_REACHED (403).
• Se a cota se esgotar no meio de uma solicitação, o Translator traduzirá o máximo que puder, retornará uma resposta bem-sucedida e relatará a insuficiência nos metadados.

Dois campos de metadados descrevem isso:

Campo	Significado
limiteAtingido	true quando a cota de palavras foi atingida durante a solicitação.
stringsIgnoradas	O número de strings deixadas no idioma de origem porque o limite foi atingido.

Quando limitReached for true, trate a resposta como parcial: o conteúdo traduzido é retornado onde possível, e as strings não traduzidas voltam ao seu texto original. Atualize seu plano para aumentar a cota.

Retentativas

Para erros transitórios (TRANSLATION_SERVICE_UNAVAILABLE em 503, ou qualquer 5xx), retente com backoff exponencial. As traduções são armazenadas em cache, portanto, as solicitações retentadas que tiveram sucesso parcial anteriormente reutilizam o trabalho existente e traduzem apenas o que ainda está faltando. Não retente erros 4xx; eles indicam um problema com a solicitação que não se resolverá sozinho.