5.1 Cara membaca galat

Semua galat berbentuk {"success": false, "error": {"code", "message"}, "request_id"}. Percabangan di kode Anda sebaiknya memakai error.code.

Bentuk lengkap respons galat ada di bagian 2.2.

5.2 Urutan pemeriksaan request

Setiap request melewati pemeriksaan berikut. Yang pertama menolak menentukan jawabannya.

#	Pemeriksaan	Jawaban bila gagal
1	Toko ada dan aktif	`404 tenant_not_found`, `403 tenant_suspended`, `503 tenant_unavailable`
2	Key tidak ada di query string	`400 invalid_request`
3	Alamat IP Anda belum melewati batas kegagalan autentikasi	`429 rate_limited`
4	Key valid, aktif, dan pemiliknya boleh memakai API	`401 invalid_api_key`, `403 account_suspended`, `403 api_access_disabled`, `403 ip_not_allowed`, `503 service_unavailable`
5	Channel Telegram toko aktif, lalu toko menyediakan API Reseller	`403 channel_disabled`, `403 plan_not_eligible`, `503 service_unavailable`
6	Batas rate per key	`429 rate_limited`
7	Slot pemrosesan per toko tersedia	`503 server_busy`
8	`POST /orders`: ukuran body	`413 payload_too_large`
9	Validasi request dan logika bisnis	Lihat bagian 5.3 sampai bagian 5.7

Catatan:

Key yang tidak dikenal dan key yang sudah dicabut dijawab identik (401 invalid_api_key, isi sama). Anda tidak bisa membedakannya dari respons, dan itu disengaja.
Status reseller, blokir, dan Akses API dibaca dari database pada setiap request, tanpa cache. Perubahan oleh toko berlaku mulai request berikutnya.
Kegagalan invalid_api_key dan ip_not_allowed dihitung per alamat IP per toko: 20 kegagalan per 5 menit. Setelah itu IP tersebut dijawab 429 rate_limited sebelum key diperiksa, termasuk untuk key yang benar, sampai hitungannya turun. Aplikasi yang salah konfigurasi key dan mengulang terus akan mengunci dirinya sendiri.

5.3 Galat toko

Kode	HTTP	Kapan	Yang dilakukan
`tenant_not_found`	404	Slug di alamat tidak valid atau toko tidak ada	Periksa slug. Jangan diulang
`tenant_suspended`	403	Toko ditangguhkan	Hubungi toko
`tenant_unavailable`	503	Toko belum aktif atau layanannya sedang tidak tersedia	Hubungi toko. Coba lagi setelah toko aktif

5.4 Galat autentikasi dan akses

Kode	HTTP	Kapan	Yang dilakukan
`invalid_request`	400	API key dikirim lewat query string	Pindahkan key ke header `Authorization`. Pertimbangkan memutar key
`invalid_api_key`	401	Header `Authorization` hilang atau bukan Bearer, format key salah, key tidak dikenal, sudah dicabut, atau berasal dari toko lain	Periksa key dan slug. Minta key baru ke toko bila perlu. Jangan diulang, setiap kegagalan dihitung
`account_suspended`	403	Akun reseller diblokir	Hubungi toko
`api_access_disabled`	403	Akses API dimatikan, akun bukan lagi reseller, atau tidak punya akun Telegram	Hubungi toko
`ip_not_allowed`	403	IP klien tidak ada di allowlist key	Minta toko menambahkan IP server Anda. Periksa alamat keluar server (NAT, proxy)
`channel_disabled`	403	Channel Telegram toko dimatikan	Hubungi toko
`plan_not_eligible`	403	Toko tidak menyediakan API Reseller	Hubungi toko. Key tidak dihapus dan berfungsi lagi setelah toko menyediakannya kembali (perubahan berlaku dalam sekitar satu menit)

5.5 Galat request dan data

Kode	HTTP	Kapan	Yang dilakukan
`invalid_request`	422	Body bukan JSON yang valid, `variant_id` bukan UUID, `quantity` di luar 1 sampai 20, field tak dikenal, `Idempotency-Key` hilang atau salah format, id di path bukan UUID, parameter `limit`, `offset`, `status`, `from`, atau `to` tidak valid	Baca `error.message`, perbaiki request. Jangan diulang tanpa perubahan
`payload_too_large`	413	Body `POST /orders` lebih dari 8 KB	Kirim body yang lebih kecil. Body yang benar hanya berisi `variant_id` dan `quantity`
`not_found`	404	Path tidak dikenal di bawah `/reseller`	Periksa path
`product_not_found`	404	Produk tidak ada, tidak aktif, terhapus, atau private tanpa izin untuk Anda	Periksa id produk. Untuk produk private, minta toko memberi izin
`variant_not_found`	404	Varian tidak ada, tidak aktif, terhapus, atau produknya private tanpa izin untuk Anda	Periksa id varian dan izin produk
`order_not_found`	404	Order tidak ada, milik pelanggan lain, atau bukan order API	Periksa id order

5.6 Galat pembelian

Kode	HTTP	Kapan	Yang dilakukan
`insufficient_balance`	402	Saldo kurang atau wallet belum ada	Top up lewat bot Telegram toko, lalu coba lagi
`insufficient_stock`	409	Stok varian habis	Aman diulang dengan key yang sama beberapa kali (bagian 3.5). Bila tetap muncul, tandai habis
`stock_reserved`	409	Stok ada tetapi sedang ditahan order pending pembeli lain	Coba lagi dalam beberapa menit
`variant_unavailable`	409	Total setelah diskon grosir kurang dari Rp 1, sehingga varian tidak bisa dibeli	Jangan diulang. Hubungi toko soal harga varian
`request_in_progress`	409	Request lain dengan `Idempotency-Key` yang sama masih diproses. Header `Retry-After: 1`	Aman diulang dengan key yang sama setelah 1 detik
`idempotency_key_reuse`	422	`Idempotency-Key` sudah dipakai untuk `variant_id` atau `quantity` yang berbeda	Pakai key baru untuk pembelian baru
`account_suspended`	403	Akun diblokir saat pembelian diproses	Hubungi toko

5.7 Galat beban dan layanan

Kode	HTTP	Kapan	Yang dilakukan
`rate_limited`	429	Batas rate per key terlampaui, atau batas kegagalan autentikasi per IP terlampaui. Header `Retry-After` berisi detik tunggu	Tunggu `Retry-After`, lalu ulangi (aman dengan key yang sama)
`server_busy`	503	Server sedang melayani batas maksimum request bersamaan untuk toko ini dan slot tidak kosong dalam 2 detik. Header `Retry-After: 1`	Tunggu 1 detik lalu ulangi (aman dengan key yang sama). Kurangi request paralel
`service_unavailable`	503	Server tidak bisa memutuskan, misalnya database atau data layanan toko tidak terbaca. Request ditolak, bukan diizinkan	Ulangi dengan jeda yang membesar (aman dengan key yang sama)
`internal_error`	500	Kesalahan di server. Detailnya tidak dikirim ke klien	Catat `request_id`. Ulangi dengan key yang sama, dan laporkan ke toko bila berulang

5.8 Pemecahan masalah

Gejala yang paling sering ditemui dan langkah pertama yang perlu dicoba.

Gejala	Kemungkinan penyebab	Yang dilakukan
`401 invalid_api_key` padahal key terasa benar	Key sudah diputar atau dicabut, `<slug>` di alamat dasar bukan toko tempat key diterbitkan, atau key terpotong atau salah ketik. Key yang tidak dikenal, dicabut, atau milik toko lain dijawab identik	Periksa slug di bagian 1.3 dan salin ulang key utuh. Bila perlu, minta toko memutar key
`429 rate_limited` sejak awal, bahkan dengan key yang benar	IP Anda sudah melewati 20 kegagalan autentikasi per 5 menit, jadi dijawab `429` sebelum key diperiksa	Perbaiki key, lalu tunggu sesuai `Retry-After` (bisa sampai 300 detik). Jangan mengulang terus
`403 ip_not_allowed`	Alamat keluar server Anda tidak ada di allowlist. Bila server keluar lewat NAT atau proxy, yang dilihat API adalah alamat keluarnya	Minta toko menambahkan alamat itu (bagian 4.2)
Respons `POST /orders` hilang, timeout, atau hasilnya tidak diketahui	Jaringan putus setelah server memproses pembelian	Ulangi dengan `Idempotency-Key` yang sama, jangan buat key baru. Bila semua percobaan habis, cek `GET /orders?idempotency_key=<key>` (bagian 3.5)
`409 request_in_progress`	Request lain dengan key yang sama masih berjalan, misalnya dua proses mengirim pembelian yang sama bersamaan	Tunggu 1 detik lalu ulangi dengan key yang sama
`402 insufficient_balance`	Saldo kurang atau wallet belum ada. Top up hanya tersedia lewat bot Telegram toko	Top up, cek `GET /balance` (bagian 3.1), lalu coba lagi
`403 plan_not_eligible` atau `403 channel_disabled`	Toko tidak menyediakan API Reseller, atau channel Telegram toko dimatikan. Key tidak dihapus	Hubungi toko. Key berfungsi lagi setelah syaratnya terpenuhi (perubahan berlaku dalam sekitar satu menit)

Butuh bantuan dengan integrasi?

Sertakan request_id dari respons galat, lalu hubungi tim Ayosel lewat Telegram atau WhatsApp, atau email [email protected].