Memahami Error Code Email API: 401, 402, 403, 422, 429 dan Cara Mengatasinya

Ketika mengintegrasikan API email ke aplikasi, error code yang muncul sering kali membingungkan — terutama bagi developer yang baru pertama kali menggunakan layanan email transaksional. Artikel ini membahas semua error code Mailketing API v2, penyebab pastinya, dan cara mengatasinya dengan cepat.

Daftar Error Code Mailketing API v2

Mailketing API v2 menggunakan HTTP status code standar. Berikut ringkasan lengkapnya:

401 Unauthorized — API Token Tidak Valid

Error 401 terjadi ketika API token tidak dikirim atau token yang dikirim salah/sudah di-regenerate.

Contoh response 401

{
  "success": false,
  "data": null,
  "message": "Unauthorized",
  "errors": {}
}

4 cara mengirim token yang benar

Mailketing API v2 mendukung 4 cara pengiriman token (gunakan salah satu):

# Cara 1 — Header Authorization Bearer (direkomendasikan)
curl -X POST "https://api.mailketing.co.id/api/v2/send" 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{...}'

# Cara 2 — Header X-Api-Token
curl -X POST "https://api.mailketing.co.id/api/v2/send" 
  -H "X-Api-Token: YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{...}'

# Cara 3 — Query parameter
curl -X POST "https://api.mailketing.co.id/api/v2/send?api_token=YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{...}'

# Cara 4 — JSON body
curl -X POST "https://api.mailketing.co.id/api/v2/send" 
  -H "Content-Type: application/json" 
  -d '{"api_token": "YOUR_API_TOKEN", ...}'

Checklist debug 401

• Ambil token dari menu API Integration di dashboard Mailketing
• Pastikan tidak ada spasi atau karakter tersembunyi di awal/akhir token
• Jika menggunakan environment variable, pastikan variable sudah ter-load
• Token lama akan langsung invalid setelah di-regenerate

402 Payment Required — Kredit Habis

Error 402 muncul ketika saldo kredit akun Mailketing sudah habis. Mailketing menggunakan sistem pay-per-use — setiap email yang terkirim memotong kredit.

Cek sisa kredit via API

curl -X GET "https://api.mailketing.co.id/api/v2/credits" 
  -H "X-Api-Token: YOUR_API_TOKEN"

# Contoh response
{
  "success": true,
  "data": { "credits": 4850, "used": 150 },
  "message": "OK"
}

Handling 402 di kode PHP

$response = sendEmail($payload);
if ($response['http_code'] === 402) {
    notifyLowCredit(); // kirim alert ke tim
    queueForRetry($payload); // antrian untuk retry setelah topup
}

Best practice: monitor saldo via GET /credits secara berkala dan kirim notifikasi internal ketika kredit di bawah threshold tertentu (misalnya 500 kredit).

403 Forbidden — Domain Pengirim Belum Diverifikasi

Error 403 terjadi ketika from_email yang dikirim menggunakan domain yang belum diverifikasi di akun Mailketing. Perlu dibedakan dari 401 — token bisa valid, tapi domain pengirimnya yang bermasalah.

Penyebab umum 403

• from_email menggunakan domain berbeda dari yang sudah diverifikasi
• Domain sudah ditambahkan tapi SPF/DKIM belum dikonfigurasi dengan benar
• Typo pada from_email — misalnya [email protected] padahal yang diverifikasi [email protected]

Cek daftar sender yang sudah diverifikasi

curl -X GET "https://api.mailketing.co.id/api/v2/senders" 
  -H "X-Api-Token: YOUR_API_TOKEN"

# Pastikan from_email ada di sini dan status "verified"
{
  "success": true,
  "data": [{ "from_email": "[email protected]", "status": "verified" }],
  "message": "OK"
}

422 Unprocessable Entity — Validasi Input Gagal

Error 422 adalah error yang paling sering ditemui saat development. Request berhasil diterima server, tapi ada field yang tidak valid atau field wajib yang kosong.

Contoh response 422

{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": {
    "recipient": ["The recipient field is required."],
    "subject":   ["The subject field is required."],
    "content":   ["The content field is required."]
  }
}

Field wajib endpoint POST /send

Checklist debug 422

• Baca field errors di response — Mailketing menjelaskan field mana yang bermasalah
• Semua field wajib harus terisi dan tidak null atau string kosong
• Format email di from_email dan recipient harus valid
• Jika pakai attachment, pastikan konten base64 valid dan filename tidak kosong

429 Too Many Requests — Rate Limit

Error 429 di Mailketing API v2 berbeda dari kebanyakan API lain: rate limit hanya berlaku untuk request yang gagal. Jika aplikasi mengirim ribuan email sukses, tidak akan kena 429.

Response headers saat kena rate limit

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
Retry-After: 42

Handling 429 dengan exponential backoff (JavaScript)

async function sendWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i  setTimeout(r, retryAfter * 1000));
      continue;
    }
    return await res.json();
  }
  throw new Error('Max retries reached');
}

Jika sering kena 429, hampir pasti ada bug yang menyebabkan banyak request gagal — misalnya token salah atau sender belum diverifikasi. Perbaiki error utamanya terlebih dahulu.

FAQ

Apakah error 500 bisa di-retry?

Ya. Error 500 biasanya sementara. Implementasikan retry dengan jeda beberapa detik. Jika muncul terus lebih dari 5 menit, hubungi support Mailketing di [email protected].

Status 200 berarti email sudah sampai ke inbox?

Tidak. Status 200 berarti email berhasil masuk ke queue pengiriman Mailketing. Status aktual (delivered, bounced, spam) dipantau via dashboard Mailketing.

Apa bedanya 401 dan 403?

401 berarti token tidak ada atau salah. 403 berarti token valid, tapi domain pengirim (from_email) belum diverifikasi. Keduanya memerlukan penanganan yang berbeda.

Rate limit 429 berlaku per akun atau per IP?

Per IP. Jika deploy di beberapa server dengan IP berbeda, setiap IP mendapat kuota 30 request gagal per menit secara terpisah.

Sudah paham semua error code-nya? Baca dokumentasi lengkap Mailketing API untuk contoh kode dalam PHP, JavaScript, Python, dan Node.js — atau langsung daftar Mailketing gratis dan mulai integrasikan API email ke aplikasimu.