Error, kode status, dan batas kecepatan API

Integrasi yang andal bukan hanya soal request yang berhasil, tapi juga tahu harus berbuat apa saat request gagal. Artikel ini menjelaskan format error API kirim.id, kapan sebuah request boleh diulang, dua jenis batas kecepatan yang berlaku, serta batasan API yang perlu kamu ketahui sejak awal.

Format error#

Semua error berbentuk JSON dengan field message. Error validasi (422) juga membawa errors per field:

{
  "message": "Penerima wajib diisi. (and 1 more error)",
  "errors": {
    "to": ["Penerima wajib diisi."],
    "subject": ["Subjek wajib diisi."]
  }
}

Kode status#

Contoh logika retry#

async function kirimDenganRetry(payload, idempotencyKey) {
  const jeda = [1, 5, 30]; // detik
  for (let i = 0; ; i++) {
    let res;
    try {
      res = await fetch('https://api.kirim.id/v1/messages', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.KIRIM_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify(payload),
      });
    } catch (err) {
      if (i >= jeda.length) throw err; // error jaringan
      await new Promise((r) => setTimeout(r, jeda[i] * 1000));
      continue;
    }

    if (res.ok) return res.json();
    const bolehUlang = [429, 500, 503].includes(res.status);
    if (!bolehUlang || i >= jeda.length) {
      const body = await res.json();
      throw new Error(`${res.status}: ${body.message}`);
    }
    const tunggu = res.status === 429
      ? Number(res.headers.get('Retry-After') || jeda[i])
      : jeda[i];
    await new Promise((r) => setTimeout(r, tunggu * 1000));
  }
}

Batas request API#

• 60 request per menit per API key (tanpa key: per alamat IP). Kuota ini dipakai bersama oleh semua endpoint.

• Setiap jawaban membawa header X-RateLimit-Limit dan X-RateLimit-Remaining.

• Kalau terlampaui: 429 {"message":"Too Many Attempts."} dengan header Retry-After (detik) dan X-RateLimit-Reset (unix time).

Tips hemat kuota: cek status banyak pesan sekaligus dengan GET /v1/messages?ids=… (maks. 100 ID), dan pakai webhook alih-alih polling.

Kecepatan kirim email#

Terpisah dari batas request: email yang sudah diterima API (201 queued) dikirim bertahap sesuai jenis akun. Kalau batasnya penuh, email menunggu di antrean — tidak ditolak dan tidak perlu dikirim ulang.

Batas ini berlaku bersama untuk semua jalur kirim (aplikasi, API, SMTP relay, journey). Selama server pengiriman kirim.id dalam masa pemanasan IP, ada juga batas harian se-platform; kelebihannya dikirim hari berikutnya (hari berganti pukul 00.00 WIB).

Batasan saat ini#

• POST /messages: satu penerima per request; belum mendukung CC/BCC atau header kustom.

• Lampiran hanya lewat API — SMTP relay belum meneruskan lampiran.

• Pelacakan buka/klik dan footer unsubscribe tidak bisa dimatikan.

• Mode opt-in audience (single/double) hanya bisa diubah dari dashboard.

• POST /contacts selalu menjawab 201, termasuk untuk kontak yang sudah ada.

• Kontak yang dihapus lalu dikirimi lagi lewat API akan dibuat ulang sebagai subscribed. Untuk memblokir alamat, tambahkan ke Daftar Filter.

Langkah berikutnya#

• Autentikasi & API key — daftar pesan error 401/403.

• Kirim email lewat API — urutan pemeriksaan dan Idempotency-Key.

• Cara kerja koin — biaya dan penalti.