Lỗi và thử lại
Các lỗi nghiệp vụ trả về code và message ở cấp độ cao nhất của phần thân phản hồi. detail thường giống với message nhưng có thể là một lời giải thích ngắn gọn khác (như dưới đây); hiển thị message cho người dùng. Các thông báo bằng tiếng Trung:
{ "code": "CONCURRENCY_LIMITED", "message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交", "detail": "排队文件完成一部分后可继续提交"}Một vài lỗi nghiệp vụ chỉ trả về code. Các trường hợp xác thực thất bại trả về 422 kèm theo danh sách lỗi trường trong detail:
{ "detail": [ { "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" } ]}Xử lý lỗi theo trạng thái HTTP trước, sau đó đến code: nhiều lỗi chỉ trả về mã chung UNKNOWN_ERROR, và chỉ một số trường hợp kèm theo mã cụ thể code (như 429 trường hợp dưới đây). Ghi lại tiêu đề phản hồi X-Request-Id để phục vụ việc khắc phục sự cố.
Trạng thái HTTP
Phần tiêu đề “Trạng thái HTTP”| Trạng thái | Ý nghĩa | Lời khuyên |
|---|---|---|
400 | Yêu cầu không hợp lệ, ví dụ: cài đặt đã chọn không khả dụng | Sửa yêu cầu; không thử lại |
401 | Tín chỉ bị thiếu, không hợp lệ, đã hết hạn hoặc bị thu hồi | Thay đổi thông tin xác thực |
402 | Số dư (sau khi trừ nợ) không vượt quá ngưỡng công việc, hoặc âm; nếu sử dụng khóa API, ngân sách còn lại của khóa có thể quá thấp. | Nạp thêm (hoặc tăng ngân sách cho khóa), sau đó gửi lại |
403 | Giới hạn của khóa không cho phép thao tác này (ví dụ: cài đặt dịch thuật không được phép), tài khoản đã bị vô hiệu hóa, hoặc thao tác phải được thực hiện trên trình duyệt đã đăng nhập (chẳng hạn như quản lý khóa API) | Kiểm tra các cài đặt chính hoặc sử dụng trang web |
404 | Tài nguyên không tồn tại, đã bị xóa hoặc thuộc về tài khoản khác (cả ba trường hợp này đều trông giống nhau) | Kiểm tra ID |
409 | Khóa tính idempotent đã được sử dụng cho một yêu cầu khác, hoặc trạng thái của tài nguyên không cho phép thao tác này. | Truy vấn thao tác gốc, sau đó quyết định |
410 | Tài nguyên hoặc điểm cuối đã bị xóa vĩnh viễn, ví dụ: một điểm cuối không còn được sử dụng hoặc một tác vụ đã bị xóa gắn với một khóa tính khả idempotent. | Không thử lại |
413 | Tệp hoặc nội dung yêu cầu vượt quá giới hạn | Sử dụng một tệp nhỏ hơn |
415 | Định dạng tệp không được hỗ trợ | Sử dụng định dạng khác |
422 | Xác thực thất bại, hoặc tệp trống hoặc không có nội dung để xử lý | Sửa các trường; không tự động thử lại |
429 | Tỷ lệ, kích thước hàng đợi hoặc ngân sách bị giới hạn | Xem bên dưới |
5xx | Lỗi dịch vụ tạm thời | Rút lui theo cấp số nhân với số lần thử tối đa |
Xử lý 429
Phần tiêu đề “Xử lý 429”code | Ý nghĩa | Làm gì |
|---|---|---|
RATE_LIMITED | Quá nhiều yêu cầu | Chờ Retry-After, sau đó thử lại |
CONCURRENCY_LIMITED | Quá nhiều tác vụ dịch tệp đang trong hàng đợi | Chờ Retry-After, hoặc chờ một số tác vụ hoàn tất |
AUTH_API_KEY_QUOTA_EXCEEDED | Ngân sách của khóa đã hết | Không thử lại cho đến khi ngân sách được tăng lên |
Một 429 không có Retry-After nên được xử lý bằng phương pháp tăng dần độ chậm.
Chiến lược thử lại
Phần tiêu đề “Chiến lược thử lại”- Các truy vấn có thể được thử lại trực tiếp.
- Khi thực hiện lại yêu cầu tạo, hãy sử dụng lại
Idempotency-Keyvà chính xác cùng một nội dung yêu cầu; sử dụng một khóa mới cho mỗi lần gửi mới. - Sau khi tải lên thất bại, hãy yêu cầu một địa chỉ tải lên mới.
- Thiết lập thời gian chờ kết nối, thời gian chờ đọc và thời gian chờ tổng cho mọi yêu cầu, thêm độ lệch ngẫu nhiên vào các lần thử lại, và đặt giới hạn số lần thử.
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())