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.
Status HTTP
Seção intitulada “Status HTTP”| Status | Significado | Conselhos |
|---|---|---|
400 | Requisição inválida; por exemplo, a configuração selecionada não está disponível. | Corrija a solicitação; não tente novamente |
401 | Credencial ausente, inválida, expirada ou revogada | Alterar as credenciais |
402 | O 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 |
403 | Os 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 |
404 | O recurso não existe, foi excluído ou pertence a outra conta (os três casos parecem iguais) | Verifique o ID |
409 | A 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 |
410 | O 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 |
413 | O arquivo ou o corpo da solicitação excede o limite | Use um arquivo menor |
415 | Formato de arquivo não suportado | Use outro formato |
422 | A validação falhou ou o arquivo está vazio, sem conteúdo para processamento. | Corrija os campos; não tente novamente automaticamente |
429 | Taxa, tamanho da fila ou orçamento limitado | Veja abaixo |
5xx | Erro temporário do serviço | Retrocesso exponencial com um número máximo de tentativas |
Tratamento de 429
Seção intitulada “Tratamento de 429”code | Significado | O que fazer |
|---|---|---|
RATE_LIMITED | Demasiadas solicitações | Aguarde Retry-After e tente novamente |
CONCURRENCY_LIMITED | Há muitas tarefas de tradução de arquivos em fila | Aguarde Retry-After ou que alguns trabalhos sejam concluídos |
AUTH_API_KEY_QUOTA_EXCEEDED | O orçamento da chave foi esgotado | Não tente novamente até que o orçamento seja aumentado |
Um 429 sem Retry-After deve ser tratado com retardo exponencial.
Estratégia de retentativa
Seção intitulada “Estratégia de retentativa”- As consultas podem ser repetidas diretamente.
- Ao retentar uma solicitação de criação, reutilize o mesmo
Idempotency-Keye 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 randomimport 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())