Tangani error API

Gunakan status HTTP dan code untuk menentukan tindakan backend. Pesan membantu diagnosis, tetapi jangan membuat logika berdasarkan teks message yang bisa berubah.

Bentuk respons error

Error dikembalikan sebagai objek langsung, bukan { "error": ... }:

Contoh error konflik idempotensi

{
	"type": "conflict_error",
	"code": "idempotency_conflict",
	"message": "The idempotency key was reused with a different request.",
	"request_id": "req_example_1001"
}

Field	Penggunaan
`type`	Kategori, seperti `invalid_request_error`, `authentication_error`, atau `api_error`.
`code`	Kode machine-readable untuk percabangan penanganan error.
`message`	Penjelasan kegagalan; bukan identifier stabil.
`request_id`	ID diagnosis, sesuai header respons `X-Request-ID`.
`details`	Konteks opsional, misalnya `retry_after_seconds`.

Respons dari proxy atau gangguan jaringan mungkin bukan JSON kontrak. Periksa HTTP status dan content type sebelum parsing; siapkan jalur penanganan respons yang tidak dapat dibaca.

Perbaiki request sebelum mencoba lagi

HTTP	Kode yang umum	Tindakan
400	`content_type_required`	Kirim `Content-Type: application/json` pada POST.
400	`invalid_json`	Perbaiki sintaks JSON.
400	`idempotency_key_required`, `idempotency_key_invalid`	Sertakan key dengan format yang diterima.
401	`authentication_required`, `authentication_failed`	Periksa header dan key aktif; jangan retry dengan credential yang sama terus-menerus.
404	`payment_not_found`	Cocokkan payment ID, project, dan environment key.
409	`idempotency_conflict`	Body berubah untuk key operasi yang sama. Cari penyebab, jangan bypass dengan key acak.
409	`merchant_reference_conflict`	Referensi sudah dipakai. Cari payment yang terkait dengan pesanan.
409	`test_environment_required`	Simulator hanya menerima key TEST.
413	`request_body_too_large`	Kurangi ukuran body.
422	`validation_error`	Periksa field wajib, tipe amount, channel, dan field tambahan yang tidak didukung.

Tidak semua kode berlaku pada semua endpoint. Detail respons per operasi ada pada API Reference. Kesalahan konfigurasi atau operasi internal juga dapat menghasilkan error umum; jangan berasumsi semua HTTP 500 berasal dari gangguan sementara.

Batasi retry untuk kegagalan sementara

Kondisi	Tindakan yang aman
HTTP 429 `rate_limit_exceeded`	Tunggu sesuai `Retry-After` atau `details.retry_after_seconds` yang valid, lalu retry dengan batas percobaan.
HTTP 503 `rate_limit_unavailable`	Layanan pembatas request tidak tersedia; beri jeda, jangan memperbanyak request.
HTTP 500 `internal_error`	Periksa status payment jika ID tersedia; retry hanya sesuai keamanan operasi dan hentikan jika terus gagal.
Timeout / koneksi putus	Hasil operasi belum diketahui, bukan pasti gagal. Untuk create, gunakan key dan body yang sama.

Gunakan exponential backoff dengan jitter dan jumlah percobaan terbatas. Jangan retry pada setiap error tanpa membedakan endpoint.

Pada create payment, ulang dengan API key, idempotency key, dan body yang sama. Pada retrieve, baca ulang dengan jeda. Pada simulasi, jangan retry otomatis karena percobaan tidak dideduplikasi. Lihat idempotensi.

Beri pelanggan pesan yang tepat

Jika hasil belum diketahui, tampilkan “Status pembayaran sedang diperiksa”, bukan “Pembayaran gagal”.
Jika autentikasi atau konfigurasi backend bermasalah, jangan meminta pelanggan mengganti API key.
Jika payment sudah failed atau expired, tampilkan hasil payment, bukan stack trace API.
Jangan memperbarui pesanan menjadi paid dari respons error atau dari input frontend.

Informasi untuk diagnosis

Catat endpoint relatif, metode, HTTP status, code, request_id, waktu kejadian, dan environment. Sertakan ID payment atau referensi fixture hanya di kanal dukungan yang sesuai.

Jangan mencatat Bearer token, webhook secret, signature lengkap, checkout URL privat, payload provider, atau seluruh body pelanggan. Masking setelah log tersimpan bukan pengganti pencegahan.

Error signature pada receiver Anda bukan error endpoint API Valcentra. Ikuti panduan HMAC dan retry webhook untuk arah request tersebut.

Lanjutkan ke: Quickstart untuk contoh request yang benar, atau sandbox untuk pengujian kegagalan.