Skip to content

Errors and retries

Business errors return code and message at the top level of the response body. detail is usually the same as message but can be a different, shorter explanation (as below); show message to users. Messages are in Chinese:

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

A few business errors return only code. Validation failures return 422 with a list of field errors in detail:

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

Handle errors by HTTP status first, then by code: many errors return only the generic UNKNOWN_ERROR, and only some carry a specific code (such as the 429 cases below). Record the X-Request-Id response header for troubleshooting.

StatusMeaningAdvice
400Invalid request, for example the chosen setting is unavailableFix the request; do not retry
401Credential missing, invalid, expired or revokedChange the credential
402The balance (after debt) is not above the job threshold, or it is negative; with an API key, the key’s remaining budget may be too lowTop up (or raise the key’s budget), then submit again
403The key’s limits do not allow this operation (for example the translation setting is not allowed), the account is disabled, or the operation must be done in a signed-in browser (such as managing API keys)Check the key settings or use the website
404The resource does not exist, was deleted or belongs to another account (all three look the same)Check the ID
409The idempotency key was used for a different request, or the resource’s state does not allow the operationQuery the original operation, then decide
410The resource or endpoint is permanently gone, for example a retired endpoint or a deleted job behind an idempotency keyDo not retry
413The file or request body exceeds the limitUse a smaller file
415Unsupported file formatUse another format
422Validation failed, or the file is empty or has nothing to processFix the fields; do not retry automatically
429Rate, queue size or budget limitedSee below
5xxTemporary service errorExponential backoff with a maximum number of attempts
codeMeaningWhat to do
RATE_LIMITEDToo many requestsWait for Retry-After, then retry
CONCURRENCY_LIMITEDToo many file translation jobs are queuedWait for Retry-After, or for some jobs to finish
AUTH_API_KEY_QUOTA_EXCEEDEDThe key’s budget is used upDo not retry until the budget is raised

A 429 without Retry-After should be handled with exponential backoff.

  • Queries can be retried directly.
  • When retrying a create request, reuse the same Idempotency-Key and the exact same body; use a new key for each new submission.
  • After a failed upload, request a new upload address.
  • Set connect, read and total timeouts for every request, add random jitter to retries, and cap the number of attempts.
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())