Kesalahan dan pengulangan
Kesalahan bisnis mengembalikan code dan message pada tingkat teratas dari badan respons. detail biasanya sama dengan message, tetapi dapat berupa penjelasan yang berbeda dan lebih singkat (seperti di bawah); tampilkan message kepada pengguna. Pesan-pesan tersebut dalam bahasa Mandarin:
{ "code": "CONCURRENCY_LIMITED", "message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交", "detail": "排队文件完成一部分后可继续提交"}Beberapa kesalahan bisnis hanya mengembalikan code. Kegagalan validasi mengembalikan 422 beserta daftar kesalahan bidang dalam detail:
{ "detail": [ { "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" } ]}Tangani kesalahan berdasarkan status HTTP terlebih dahulu, kemudian berdasarkan code: banyak kesalahan hanya mengembalikan UNKNOWN_ERROR generik, dan hanya sebagian yang menyertakan code spesifik (seperti 429 kasus di bawah). Catat header respons X-Request-Id untuk pemecahan masalah.
Status HTTP
Section titled “Status HTTP”| Status | Arti | Saran |
|---|---|---|
400 | Permintaan tidak valid, misalnya pengaturan yang dipilih tidak tersedia | Perbaiki permintaan; jangan coba lagi |
401 | Kredensial hilang, tidak valid, kedaluwarsa, atau dicabut | Ubah kredensial |
402 | Saldo (setelah dikurangi utang) tidak melebihi ambang batas pekerjaan, atau bernilai negatif; dengan kunci API, anggaran sisa kunci mungkin terlalu rendah. | Isi ulang (atau tingkatkan anggaran kunci), lalu kirimkan kembali |
403 | Batasan kunci tidak mengizinkan operasi ini (misalnya, pengaturan terjemahan tidak diizinkan), akun dinonaktifkan, atau operasi harus dilakukan melalui browser yang sudah masuk (seperti saat mengelola kunci API) | Periksa pengaturan utama atau gunakan situs web |
404 | Sumber daya tidak ada, telah dihapus, atau dimiliki oleh akun lain (ketiganya tampak sama) | Periksa ID |
409 | Kunci idempotensi digunakan untuk permintaan yang berbeda, atau status sumber daya tidak memungkinkan operasi tersebut | Lakukan query pada operasi asli, lalu tentukan |
410 | Sumber daya atau titik akhir tersebut telah hilang secara permanen, misalnya titik akhir yang sudah tidak digunakan lagi atau pekerjaan yang dihapus di balik kunci idempotensi. | Jangan coba lagi |
413 | File atau badan permintaan melebihi batas | Gunakan file yang lebih kecil |
415 | Format file tidak didukung | Gunakan format lain |
422 | Validasi gagal, atau file kosong atau tidak ada yang dapat diproses | Perbaiki bidang; jangan coba lagi secara otomatis |
429 | Tingkat, ukuran antrian, atau anggaran terbatas | Lihat di bawah |
5xx | Kesalahan layanan sementara | Pengembalian eksponensial dengan jumlah upaya maksimum |
Penanganan 429
Section titled “Penanganan 429”code | Arti | Apa yang harus dilakukan |
|---|---|---|
RATE_LIMITED | Terlalu banyak permintaan | Tunggu Retry-After, lalu coba lagi |
CONCURRENCY_LIMITED | Terlalu banyak pekerjaan penerjemahan file yang tertunda dalam antrian | Tunggu Retry-After, atau hingga beberapa pekerjaan selesai |
AUTH_API_KEY_QUOTA_EXCEEDED | Anggaran kunci telah habis | Jangan coba lagi sampai anggaran dinaikkan |
A 429 tanpa Retry-After harus ditangani dengan eksponensial backoff.
Strategi pengulangan
Section titled “Strategi pengulangan”- Kueri dapat dicoba ulang secara langsung.
- Saat mencoba ulang permintaan pembuatan, gunakan kembali
Idempotency-Keyyang sama dan isi yang persis sama; gunakan kunci baru untuk setiap pengiriman baru. - Setelah pengunggahan gagal, mintalah alamat unggahan baru.
- Tetapkan batas waktu koneksi, baca, dan total untuk setiap permintaan, tambahkan jitter acak pada pengulangan, dan batasi jumlah upaya.
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())