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.
HTTP status
Section titled “HTTP status”| Status | Meaning | Advice |
|---|---|---|
400 | Invalid request, for example the chosen setting is unavailable | Fix the request; do not retry |
401 | Credential missing, invalid, expired or revoked | Change the credential |
402 | The 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 low | Top up (or raise the key’s budget), then submit again |
403 | The 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 |
404 | The resource does not exist, was deleted or belongs to another account (all three look the same) | Check the ID |
409 | The idempotency key was used for a different request, or the resource’s state does not allow the operation | Query the original operation, then decide |
410 | The resource or endpoint is permanently gone, for example a retired endpoint or a deleted job behind an idempotency key | Do not retry |
413 | The file or request body exceeds the limit | Use a smaller file |
415 | Unsupported file format | Use another format |
422 | Validation failed, or the file is empty or has nothing to process | Fix the fields; do not retry automatically |
429 | Rate, queue size or budget limited | See below |
5xx | Temporary service error | Exponential backoff with a maximum number of attempts |
Handling 429
Section titled “Handling 429”code | Meaning | What to do |
|---|---|---|
RATE_LIMITED | Too many requests | Wait for Retry-After, then retry |
CONCURRENCY_LIMITED | Too many file translation jobs are queued | Wait for Retry-After, or for some jobs to finish |
AUTH_API_KEY_QUOTA_EXCEEDED | The key’s budget is used up | Do not retry until the budget is raised |
A 429 without Retry-After should be handled with exponential backoff.
Retry strategy
Section titled “Retry strategy”- Queries can be retried directly.
- When retrying a create request, reuse the same
Idempotency-Keyand 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 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())