Di halaman ini
Error & rate limit
Format error
Semua error memakai envelope yang sama:
json
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validasi gagal",
"details": [
{ "field": "domainId", "issue": "Invalid input" }
],
"requestId": "01HXY..."
}
}
code— enum machine-readable. Cabang logika daricode, bukanmessage.message— pesan human-readable (bahasa Indonesia).details— opsional. UntukVALIDATION_FAILEDberisi array{ field, issue }.requestId— sama dengan headerX-Request-Id. Sertakan saat lapor masalah.
Katalog kode error
| HTTP | code | Kapan |
|---|---|---|
| 400 | BAD_REQUEST | Request malformed (mis. URL webhook di-blok) |
| 401 | UNAUTHORIZED | Sesi/kredensial tidak ada atau salah |
| 401 | INVALID_TOKEN | JWT tidak valid / kedaluwarsa |
| 401 | INVALID_API_KEY | API key tidak valid, di-revoke, atau kedaluwarsa |
| 402 | PAYMENT_REQUIRED | Saldo tidak cukup — perlu topup |
| 403 | FORBIDDEN | Akses ditolak (scope kurang, resource bukan milik key, endpoint tak dukung API key) |
| 403 | SERVICE_SUSPENDED | Layanan ditangguhkan |
| 404 | NOT_FOUND | Resource/endpoint tidak ada |
| 409 | CONFLICT | Konflik data (mis. retry delivery yang sudah sukses) |
| 409 | DOMAIN_NOT_VERIFIED | Domain belum lolos verifikasi DNS |
| 409 | DOMAIN_ALREADY_EXISTS | Domain sudah terdaftar di akun lain |
| 410 | GONE | Resource sudah dihapus |
| 410 | SERVICE_DELETED | Layanan telah dihapus |
| 422 | VALIDATION_FAILED | Body/query gagal validasi (lihat details) |
| 429 | RATE_LIMIT_EXCEEDED | Melewati batas rate limit |
| 429 | QUOTA_EXCEEDED | Kuota resource habis (mis. jumlah webhook per layanan) |
| 500 | INTERNAL_ERROR | Kesalahan server |
| 502 | UPSTREAM_ERROR | Layanan eksternal gangguan |
| 503 | SERVICE_UNAVAILABLE | Sedang tidak tersedia |
| 504 | UPSTREAM_TIMEOUT | Layanan eksternal timeout |
Rate limit
Rate limit dihitung per API key kalau request menyertakan X-API-Key, kalau tidak per IP klien tepercaya.
| Tier | Batas | Berlaku untuk |
|---|---|---|
| Authenticated | 1000 req / menit | Semua endpoint /v1 terautentikasi (API key / JWT) |
| Public | 30 req / menit | Endpoint /v1/public/ (per IP) |
| Payment callback | 60 req / menit | /v1/payment/callback/ (per IP) |
| Unlock | 5 req / 15 menit | /v1/public/unlock (anti brute-force, per IP) |
Header response
Pada response terautentikasi:
X-RateLimit-Limit— batas tierX-RateLimit-Remaining— sisa quota
429 RATE_LIMIT_EXCEEDED), response menyertakan Retry-After (detik) — tunggu segitu sebelum mencoba lagi.
Catatan: hanya X-RateLimit-Remaining yang di-expose lintas origin (CORS). X-RateLimit-Limit terbaca pada request same-origin.