Kesalahan

Saat permintaan API gagal, badges.ninja mengembalikan respons kesalahan JSON dengan kode status HTTP yang sesuai.

Format Kesalahan

Semua kesalahan mengikuti struktur ini:

{
  "error": "description of what went wrong"
}

Kode Status

Kode	Arti	Kapan Terjadi
400	Bad Request	Parameter hilang atau tidak valid, batas paket atau kuota tercapai, fitur memerlukan paket yang lebih tinggi, atau tidak berwenang — semua kegagalan validasi mengembalikan 400
402	Payment Required	Dicadangkan untuk kehabisan kredit. API lencana saat ini tidak mengurangi kredit, sehingga kode ini tidak pernah dikembalikan dalam praktik
404	Not Found	Sumber daya yang diminta tidak ada
500	Internal Server Error	Terjadi kesalahan tak terduga di server

Tidak ada 403 atau 429: kegagalan otorisasi mengembalikan 400 ("not authorized") dan tidak ada pembatasan laju (rate limiting) pada lapisan aplikasi.

Kesalahan Umum dan Solusinya

Parameter wajib tidak ada

{ "error": "missing required parameters: name, url, email" }

Solusi: Sertakan semua parameter wajib dalam body permintaan Anda. Periksa dokumentasi endpoint untuk daftar lengkapnya.

Email tidak valid

{ "error": "invalid email" }

Solusi: Berikan alamat email yang valid dengan format user@domain.com.

URL tidak valid

{ "error": "invalid URL" }

Solusi: Berikan URL lengkap beserta protokolnya, misalnya https://example.com.

Nama terlalu pendek

{ "error": "name must be at least 3 characters" }

Solusi: Gunakan nama yang lebih panjang. Nama penerbit memerlukan minimal 3 karakter. Nama penerima memerlukan minimal 5 karakter.

Penerbit belum diverifikasi

{ "error": "issuer must be verified before creating badges" }

Solusi: Verifikasi penerbit terlebih dahulu. Periksa email penerbit untuk tautan verifikasi, atau gunakan endpoint Verifikasi Penerbit.

Kuota kredensial tercapai (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Solusi: Anda telah menggunakan seluruh kumpulan kredensial tahunan Anda (Free: 1.200/tahun, Starter: 12.000/tahun, Pro: 120.000/tahun). Kumpulan ini direset pada hari jadi pendaftaran akun Anda — bukan pada pergantian bulan kalender. Tingkatkan paket Anda untuk mendapatkan jatah yang lebih besar. Lihat Paket & Penagihan.

Batas paket tercapai (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

Batas lencana menggunakan bentuk yang sama:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

Solusi: Anda telah mencapai batas paket untuk penerbit atau lencana. Hapus sumber daya yang tidak terpakai atau tingkatkan paket Anda.

Sumber daya memiliki dependensi (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

Solusi: Hapus semua lencana yang terkait dengan penerbit sebelum menghapus penerbit. Demikian pula, hapus semua kredensial di bawah sebuah lencana sebelum menghapus lencana tersebut.

Tidak berwenang (400)

{ "error": "not authorized" }

Kegagalan otorisasi adalah kesalahan validasi, sehingga mengembalikan 400 (bukan 401 atau 403).

Solusi: Anda hanya dapat memodifikasi sumber daya milik Anda sendiri. Pastikan Anda menggunakan kunci API yang benar.

HTML dalam teks berbagi

{ "error": "HTML tags are not allowed" }

Solusi: Teks berbagi harus berupa teks biasa. Hapus semua tag HTML dari parameter teks.