Status & Dukungan

Diagnosis sebelum eskalasi

Hampir setiap kegagalan yang dilaporkan adalah salah satu dari lima hal, dan masing-masing memiliki ciri yang dapat dibedakan:

Gejala	Kemungkinan penyebab	Tempat mencari
`401 unauthorized` pada panggilan yang kemarin berhasil	Kunci dirotasi, dinonaktifkan, atau headernya hilang pada salah satu jalur kode	Autentikasi
`402 insufficient_balance`	Saldo di bawah reservasi untuk pengiriman ini	Akun & saldo
Satu permintaan mengembalikan `200` tetapi tidak ada yang ditagih	Seluruh kombinasi gagal; status HTTP bukan hasil akhirnya	Penagihan & pengembalian dana
Permintaan yang sama berhasil dan gagal secara bergantian	Pembatasan laju, atau `Idempotency-Key` yang dipakai ulang untuk payload berbeda	Batas laju, Idempotensi
Tugas massal tertahan di `processing` dan `last_progress_at` berhenti bergerak	Tugas yang benar-benar macet, bukan sekadar lambat	Status tugas

Kasus last_progress_at perlu dinyatakan secara lugas: waktu yang berlalu bukan sinyal kegagalan, stempel waktu yang berhenti bergerak adalah sinyalnya. Tugas dengan 500,000 baris dapat berjalan lama secara wajar. Tugas yang last_progress_at-nya tidak bergerak adalah tugas yang perlu dieskalasi.

Apa yang perlu disertakan dalam permintaan dukungan

Setiap field di bawah ini dikembalikan oleh API, yang berarti menyertakannya tidak merugikan Anda dan menghemat satu putaran komunikasi:

Sertakan	Asalnya
`request_id`	Setiap respons realtime, termasuk kegagalan yang mengembalikan body
`task_id`	Setiap pengiriman massal dan setiap respons status tugas
`api_key_id`	`GET /v1/api-key` — mengidentifikasi kunci tanpa mengeksposnya
Status HTTP dan body respons yang tepat	Log Anda sendiri; khususnya field `code`
Stempel waktu UTC dengan detik	Log Anda sendiri
Permintaan yang Anda kirim, dengan kunci disamarkan	Kode Anda sendiri

Jangan pernah menempelkan kunci API ke permintaan dukungan. api_key_id mengidentifikasi kunci, dan kunci itu sendiri memberi akses ke saldo Anda.

Komunikasi insiden

Pemberitahuan tingkat akun — pemeliharaan terjadwal, kapasitas menurun — muncul di Konsol, yang juga menjadi tempat saldo dan catatan berada. API menyampaikan kondisi yang sama langsung ke integrasi Anda, sebagai kode error alih-alih prosa:

Kode	Artinya bagi integrasi yang berjalan
`detection_capacity_unavailable`	Tidak ada kapasitas saat ini. Mundur lalu coba lagi; tidak ada yang ditagih.
`realtime_route_unavailable`	Tidak ada rute realtime yang tersedia. Mundur lalu coba lagi.
`realtime_rate_limiter_unavailable`	Limiter-nya sendiri mati, sehingga penerimaan permintaan tidak dapat diputuskan. Coba lagi nanti.
`realtime_fact_cache_unavailable`	Dependensi realtime mati. Coba lagi nanti.

Ini semua adalah 503 dan semuanya termasuk kelompok “tunggu, lalu coba lagi” — lihat Kode Kesalahan untuk pengelompokan lengkapnya, termasuk kegagalan mana yang aman dicoba ulang dengan Idempotency-Key yang sama.

Posisi platform saat ini

Dua fakta operasional dapat diverifikasi dari luar dan perlu diketahui sebelum Anda mengajukan insiden:

API dilayani di balik Cloudflare, sehingga jalur jaringan dan terminasi TLS dioperasikan oleh Cloudflare, bukan pada satu host origin.
Setiap respons membawa X-RateLimit-Remaining, sehingga klien yang mencatat header respons dapat membedakan “dibatasi oleh batas saya sendiri” dari “layanan sedang mati” tanpa bertanya kepada siapa pun. Grup umum dan deteksi juga membawa X-RateLimit-Limit pada setiap respons; realtime tidak, karena realtime menggunakan token bucket, bukan plafon tetap per menit.

Berikutnya

Kode Kesalahan — kelompok percobaan ulang, tabel triase tercepat
Keamanan — penanganan kunci, merotasi kunci, dan apa yang tidak boleh pernah dikirim