Kesalahan

Kesalahan berbagi satu amplop (lihat ikhtisar). Lakukan percabangan berdasarkan code, catat meta.request_id di log, dan perlakukan message sebagai teks bahasa Inggris untuk manusia.

Kesalahan klien

Kode	Status	Arti dan yang harus dilakukan
validation_failed	400	Sebuah field gagal validasi. field menyebut namanya; details menjelaskan. Perbaiki field tersebut.
bad_request	400	Permintaan sama sekali tidak dapat dibaca: JSON rusak, stream Content-Encoding yang rusak, body yang terputus. Tidak ada field yang perlu diperbaiki; periksa transportnya.
validation_error	400	X-Account-Id dikirim ke endpoint yang melarangnya (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Kursor paginasi berumur lebih dari 24 jam. Mulai daftar dari awal.
unauthenticated	401	Token tidak ada atau tidak valid. Perbarui sesi atau periksa kunci.
invalid_signature	401	Tanda tangan webhook tidak terverifikasi. Lihat Webhook.
forbidden	403	Token valid tetapi tidak memiliki izin.
account_context_mismatch	403	X-Account-Id tidak cocok dengan akun pada token. Pemahaman klien tentang perusahaan saat ini sudah bergeser; baca ulang dari sesi.
not_found	404	Resource tidak ada atau milik akun atau situs lain. API tidak pernah membedakan keduanya.
conflict	409	Konflik status: optimistic lock, batasan unik, atau tindakan yang tidak diizinkan pada status saat ini (misalnya menulis ke percakapan yang sudah digabung).
idempotency_key_conflict	409	Idempotency-Key digunakan ulang dengan body yang berbeda.
payload_too_large	413	Body melebihi batas untuk keluarga endpoint ini.
unsupported_media_type	415	Content-Type salah.
unprocessable	422	JSON valid, tetapi aturan bisnis menolaknya (misalnya slot pemesanan di luar jam kerja).
storage_quota_exceeded	422	Akun mencapai batas penyimpanan paketnya. details berisi used_bytes, quota_bytes, dan requested_bytes; kosongkan ruang atau tingkatkan paket.
rate_limited	429	Perlambat. Patuhi Retry-After dan details.retry_after_seconds.

Kesalahan server

Kode	Status	Arti dan yang harus dilakukan
internal_error	500	Kegagalan tak terduga. Coba ulang sekali, lalu hubungi dukungan dengan request_id.
upstream_unavailable	502	Gateway sama sekali tidak dapat menjangkau layanan. Percobaan ulang singkat biasanya berhasil.
service_unavailable	503	Pemeliharaan terjadwal atau circuit breaker yang terbuka. Coba ulang setelah waktu di header Retry-After.
ai_vendor_out_of_funds	503	Penyedia AI Anda menolak panggilan karena alasan penagihan (402 atau 429 kuota dari vendor). Isi ulang saldo akun vendor; mencoba ulang tidak akan membantu.
upstream_timeout	504	Layanan tidak menjawab tepat waktu. Coba ulang jika retry_after tersedia.

Mencoba ulang

Coba ulang 429, 502, 503, 504, dan kegagalan jaringan dengan exponential backoff, dan kirim Idempotency-Key yang sama saat mencoba ulang agar penulisan tidak pernah diterapkan dua kali. Jangan mencoba ulang 4xx selain 429.