Error dan Status Code
Referensi cepat kode kesalahan di seluruh permukaan Hubina. Tabel lengkap per jalur ada diREST API dan SMTP.
REST API
| HTTP | error | Penyebab umum |
|---|---|---|
| 400 | invalid_request | JSON rusak, field wajib kosong, >50 penerima, subjek >998 karakter, isi >1.000.000 karakter, body >2 MB |
| 401 | unauthorized | API key tidak ada, salah format, atau dicabut |
| 403 | sender_not_authorized | Domain pengirim bukan milik akun ini atau belum terverifikasi |
| 403 | insufficient_balance | Saldo tersedia kurang dari rate akun |
| 404 | not_found | Path salah, atau memanggil host yang bukan api.hubina.net |
| 409 | billing_conflict | Idempotency-Key dipakai ulang dengan payload berbeda, atau mengulang key yang sudah gagal |
| 429 | rate_limited | >60 permintaan kirim per menit per akun + key |
| 503 | provider_unavailable | Penyedia pengiriman tidak dapat dihubungi |
| 500 | server_error | Kesalahan tak terduga; aman untuk di-retry dengan Idempotency-Key yang sama |
Format error selalu sama, dengan tambahan retryAfter untuk 429:
{
"error": "sender_not_authorized",
"message": "Sender atau domain tidak diizinkan."
}SMTP
| Kode | Penyebab umum |
|---|---|
421 4.7.0 | Koneksi bersamaan atau percobaan koneksi melebihi batas |
451 4.3.0 | Kegagalan sementara: cek domain terganggu, duplikat masih diproses, atau hasil belum pasti |
452 4.2.2 | Saldo Hubina tidak cukup |
452 4.5.3 | Penerima melebihi 50 |
452 4.7.0 | Rate limit pengiriman (300 pesan/jam per key) |
504 5.5.4 | Mekanisme AUTH tidak didukung (hanya PLAIN dan LOGIN) |
530 5.7.0 | Perintah dikirim sebelum autentikasi |
535 5.7.8 | API key salah atau dicabut |
538 5.7.0 | Autentikasi dicoba sebelum TLS (STARTTLS belum aktif) |
550 5.6.0 | Pesan tidak punya From: / Subject: yang valid |
550 5.7.0 | Message-ID yang sama dipakai dengan isi berbeda |
550 5.7.1 | Domain sender (envelope atau header) tidak terverifikasi |
552 5.3.4 | Pesan >10 MB atau header >256 KB |
554 5.7.0 | Penyedia menolak permanen saat submit — tidak ada tagihan |
Pola penanganan yang benar
- 4xx sementara (421/451/452 4.7.0): retry dengan backoff. Pakai
Message-ID(SMTP) atauIdempotency-Key(REST) yang sama. - 5xx permanen (535/550/552/554): jangan ulangi tanpa memperbaiki penyebabnya.
- Saldo (452 4.2.2 / 403 insufficient_balance): top up; retry setelah saldo cukup.
- 503 provider_unavailable: gangguan sementara di sisi penyedia; retry bertahap, tidak ada tagihan untuk percobaan yang gagal total.