Error & Batas Laju
Bentuk respons error, tabel lengkap kode status HTTP, perilaku batas laju, dan strategi percobaan ulang yang cocok untuk Atlas Cloud.
Bentuk respons error
Atlas Cloud mengembalikan tiga bentuk error yang berbeda, bergantung pada bagian API mana yang Anda panggil. Pastikan bentuknya sebelum menulis parser.
Digunakan oleh endpoint protokol LLM dan endpoint pembuatan media:
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Setiap respons membawa header X-Request-ID. Catat header tersebut — itulah cara tercepat bagi tim dukungan untuk melacak sebuah panggilan tertentu.
Kode status HTTP
| Status | Arti | Yang harus dilakukan |
|---|---|---|
400 | Permintaan tidak valid: body tidak dapat diurai, model tidak ada, content type keliru, header retensi tidak valid, atau webhook_url tidak valid | Perbaiki permintaannya. Bidang msg menyebutkan masalah spesifiknya |
401 | Autentikasi gagal — key tidak ada, tidak dikenali, atau kedaluwarsa | Periksa key-nya. Perlu dicatat, jalur URL yang salah juga mengembalikan 401, jadi periksa endpoint-nya juga |
402 | Saldo tidak mencukupi, atau jatah Coding Plan sudah habis | Isi ulang saldo |
403 | Akun atau pengguna tidak diizinkan — termasuk memakai key Coding Plan pada model yang tidak menerimanya | Periksa cakupan key, atau hubungi dukungan |
404 | Sumber daya tidak ditemukan. Untuk model, ini juga mencakup model yang tidak tersedia bagi akun Anda | Cocokkan ID model dengan katalog |
413 | Body permintaan melebihi 50 MB | Kirim URL alih-alih Base64 sebaris, atau unggah berkasnya terlebih dahulu |
429 | Batas laju tercapai | Tunggu sejenak lalu ulangi — lihat di bawah |
451 | Diblokir di wilayah Anda | Tidak perlu diulang |
500 | Error internal | Ulangi sekali, lalu laporkan dengan menyertakan request ID |
503 | Sementara tidak tersedia | Ulangi dengan backoff |
504 | Permintaan sinkron melewati batas waktu tunggu maksimum | Beralih ke alur asinkron dan gunakan polling |
Kode 401 tidak selalu berarti key Anda salah. Gateway melakukan autentikasi sebelum perutean, sehingga salah ketik pada jalur juga menghasilkan 401, bukan 404. Jika key tersebut berfungsi di tempat lain, periksa URL-nya lebih dulu.
Kode error tingkat tugas
Ketika sebuah tugas asinkron gagal, data.error_code membawa kode platform berupa angka yang lebih spesifik daripada status HTTP. Misalnya, 1039 menandakan masukan ditolak oleh moderasi konten.
data.error memuat deskripsi yang dapat dibaca manusia. Catat keduanya, beserta prediction ID.
Batas laju
Batas laju berlaku per akun dan per model. Melampauinya akan mengembalikan 429.
Endpoint LLM dan media tidak mengembalikan X-RateLimit-Limit, X-RateLimit-Remaining, maupun Retry-After. Anda tidak dapat membaca sisa kuota dari header respons — terapkan backoff di sisi klien.
Pengecualiannya adalah endpoint penagihan /public/v1: respons 429 di sana memang menyertakan Retry-After.
Jika Anda membutuhkan batas yang lebih tinggi untuk beban kerja produksi, hubungi kami dengan menyebutkan perkiraan volume permintaan dan model yang dipakai.
Strategi percobaan ulang
Ulangi permintaan pada 429, 500, 503, dan 504, serta pada kegagalan tingkat jaringan. Jangan mengulang 400, 401, 402, 403, 404, atau 451 — hasilnya akan sama saja.
Permintaan baca boleh diulang sesuka Anda. Berhati-hatilah saat mengulang pengiriman tugas pembuatan: permintaan yang kehabisan waktu mungkin sebenarnya sudah diterima, dan pengulangan membabi buta dapat menciptakan — sekaligus menagih — tugas kedua. Lebih baik kirim tugas secara asinkron lalu lakukan polling, sehingga respons yang hilang tidak pernah berarti tugas yang hilang.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Exponential backoff + jitter, agar banyak klien tidak mengulang bersamaan
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseError saat streaming
Ketika permintaan streaming gagal sebelum stream terbuka, Anda menerima error HTTP biasa. Setelah stream dimulai, koneksi tetap terbuka dan error datang sebagai event di dalam stream — sehingga 200 pada panggilan streaming tidak menjamin respons yang lengkap. Selalu tangani penghentian di tengah stream.
Stream juga dapat memuat baris komentar SSE yang diawali : sebagai sinyal keep-alive. Baris tersebut bukan data dan harus diabaikan — sebagian besar klien SSE menanganinya untuk Anda, tetapi parser buatan sendiri sering kali tidak.
Meminta bantuan
Saat melaporkan masalah, sertakan:
- Header
X-Request-IDdari respons yang gagal - Prediction ID, untuk tugas asinkron
- ID model yang persis dan waktu kejadiannya
Hubungi kami melalui Dukungan.
Terkait
Last updated on