Error, idempotensi & retry

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo tersedia belum cukup untuk nomor ini."
  }
}

Gunakan error.code untuk cabang program, error.message untuk pesan pengguna. Jangan bergantung pada terjemahan message. RequestError dari api() menyimpan code, message, dan status. NETWORK_ERROR dengan status 0 berasal dari client, bukan status HTTP server.

import { RequestError } from "@/lib/ping/client";

function classifyFailure(error: unknown) {
  if (!(error instanceof RequestError)) return "inspect";
  if (error.code === "UNAUTHENTICATED") return "sign-in";
  if (["PRICE_CHANGED", "PRICE_OPTION_UNAVAILABLE"].includes(error.code)) {
    return "refresh-quote-and-confirm";
  }
  if (error.code === "INSUFFICIENT_BALANCE") return "top-up";
  if (error.status === 0 || error.status >= 500) return "check-existing-intent";
  return "show-error-and-refresh";
}

Idempotensi order dan top-up memakai clientRequestId pada body JSON. Header Idempotency-Key tidak dibaca oleh kedua route ini. Buat UUID sekali sebelum request pertama, simpan bersama pilihan dan nominal pending, lalu jangan ganti nilainya karena error jaringan.

1. 01

   Jangan mengartikan timeout sebagai gagal beli

   Provider mungkin sudah menerbitkan nomor atau QR walaupun respons tidak sampai. Jangan mengganti UUID, membuat top-up lain, atau membebaskan hold di client.

2. 02

   Pulihkan resource yang ada

   Jika ID diketahui, baca detail. Untuk top-up, GET pembayaran aktif. Untuk order, tampilkan daftar milik akun; jika UUID awal masih diketahui, recovery request harus memakai UUID dan payload yang sama, bukan retry otomatis dengan intent baru.

3. 03

   Tunggu rekonsiliasi bila masih ambigu

   Jika message menyebut konfirmasi provider atau error PURCHASE_UNRESOLVED/RECONCILIATION_REQUIRED, lanjutkan pembacaan terbatas dan biarkan scheduler/provider menyelesaikan hasilnya.

4. 04

   Mulai intent baru hanya setelah jelas

   Jika pengguna benar-benar memilih transaksi baru setelah hasil sebelumnya diketahui, baru buat UUID baru. Perubahan harga memerlukan konfirmasi ulang.

Status berikut berasal dari pemetaan apiHandler. Endpoint webhook dapat memberi override status untuk redelivery; contohnya RECONCILIATION_REQUIRED pada webhook Tiger menjadi 503. Tidak semua kode muncul pada setiap endpoint.

Batas jumlah order aktif, frekuensi pembelian, provider budget, dan backoff adalah pengaturan/koordinasi server. Jangan menulis asumsi kuota tetap atau menjanjikan X-RateLimit/Retry-After pada semua error. Retry baca harus terbatas dan berhenti pada 401/403/404 yang tidak bisa dipulihkan otomatis.