Lewati ke konten

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.

StatusArtiSaran
400Permintaan tidak valid, misalnya pengaturan yang dipilih tidak tersediaPerbaiki permintaan; jangan coba lagi
401Kredensial hilang, tidak valid, kedaluwarsa, atau dicabutUbah kredensial
402Saldo (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
403Batasan 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
404Sumber daya tidak ada, telah dihapus, atau dimiliki oleh akun lain (ketiganya tampak sama)Periksa ID
409Kunci idempotensi digunakan untuk permintaan yang berbeda, atau status sumber daya tidak memungkinkan operasi tersebutLakukan query pada operasi asli, lalu tentukan
410Sumber 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
413File atau badan permintaan melebihi batasGunakan file yang lebih kecil
415Format file tidak didukungGunakan format lain
422Validasi gagal, atau file kosong atau tidak ada yang dapat diprosesPerbaiki bidang; jangan coba lagi secara otomatis
429Tingkat, ukuran antrian, atau anggaran terbatasLihat di bawah
5xxKesalahan layanan sementaraPengembalian eksponensial dengan jumlah upaya maksimum
codeArtiApa yang harus dilakukan
RATE_LIMITEDTerlalu banyak permintaanTunggu Retry-After, lalu coba lagi
CONCURRENCY_LIMITEDTerlalu banyak pekerjaan penerjemahan file yang tertunda dalam antrianTunggu Retry-After, atau hingga beberapa pekerjaan selesai
AUTH_API_KEY_QUOTA_EXCEEDEDAnggaran kunci telah habisJangan coba lagi sampai anggaran dinaikkan

A 429 tanpa Retry-After harus ditangani dengan eksponensial backoff.

  • Kueri dapat dicoba ulang secara langsung.
  • Saat mencoba ulang permintaan pembuatan, gunakan kembali Idempotency-Key yang 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 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())