Pular para o conteúdo

Erros e tentativas de reenvio

Erros comerciais retornam code e message no nível superior do corpo da resposta. detail geralmente é igual a message, mas pode ser uma explicação diferente e mais curta (conforme abaixo); exiba message para os usuários. As mensagens estão em chinês:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

Alguns erros de negócios retornam apenas code. Falhas de validação retornam 422 com uma lista de erros de campo em detail:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

Trate os erros primeiro pelo status HTTP e, em seguida, pelo code: muitos erros retornam apenas o genérico UNKNOWN_ERROR, e somente alguns apresentam um code específico (como os 429 casos abaixo). Registre o cabeçalho de resposta X-Request-Id para fins de solução de problemas.

StatusSignificadoConselhos
400Requisição inválida; por exemplo, a configuração selecionada não está disponível.Corrija a solicitação; não tente novamente
401Credencial ausente, inválida, expirada ou revogadaAlterar as credenciais
402O saldo (após débitos) não ultrapassa o limite de trabalho, ou é negativo; com uma chave de API, o orçamento restante da chave pode ser insuficiente.Recarregue (ou aumente o orçamento da chave) e envie novamente
403Os limites da chave não permitem esta operação (por exemplo, a configuração de tradução não é permitida), a conta está desativada ou a operação deve ser realizada em um navegador com sessão iniciada (como ao gerenciar chaves de API)Verifique as configurações principais ou utilize o site
404O recurso não existe, foi excluído ou pertence a outra conta (os três casos parecem iguais)Verifique o ID
409A chave de idempotência foi utilizada para uma solicitação diferente, ou o estado do recurso não permite a operação.Consulte a operação original e, em seguida, decida
410O recurso ou ponto de extremidade foi removido permanentemente, por exemplo, um ponto de extremidade desativado ou um trabalho excluído associado a uma chave de idempotência.Não tentar novamente
413O arquivo ou o corpo da solicitação excede o limiteUse um arquivo menor
415Formato de arquivo não suportadoUse outro formato
422A validação falhou ou o arquivo está vazio, sem conteúdo para processamento.Corrija os campos; não tente novamente automaticamente
429Taxa, tamanho da fila ou orçamento limitadoVeja abaixo
5xxErro temporário do serviçoRetrocesso exponencial com um número máximo de tentativas
codeSignificadoO que fazer
RATE_LIMITEDDemasiadas solicitaçõesAguarde Retry-After e tente novamente
CONCURRENCY_LIMITEDHá muitas tarefas de tradução de arquivos em filaAguarde Retry-After ou que alguns trabalhos sejam concluídos
AUTH_API_KEY_QUOTA_EXCEEDEDO orçamento da chave foi esgotadoNão tente novamente até que o orçamento seja aumentado

Um 429 sem Retry-After deve ser tratado com retardo exponencial.

  • As consultas podem ser repetidas diretamente.
  • Ao retentar uma solicitação de criação, reutilize o mesmo Idempotency-Key e o corpo exatamente igual; utilize uma nova chave para cada novo envio.
  • Após um carregamento malsucedido, solicite um novo endereço de upload.
  • Defina os tempos limite de conexão, leitura e total para cada requisição, adicione jitter aleatório às tentativas de retransmissão e limite o número de tentativas.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())