Panduan

Penanganan error

Parameter yang tidak valid dibalas 422 beserta rincian per field.

bash

curl -s -H "X-API-Key: $MASKI_API_KEY" "https://api.maski.cloud/api/kjsb?per_page=0"

json

{
  "status": false,
  "message": "Data yang diberikan tidak valid.",
  "errors": [{ "attribute": "per_page", "text": "Number must be greater than 0" }]
}

Perhatikan

Kesalahan yang paling sering: sort harus huruf besar (ASC/DESC). sort=asc ditolak 422.

Kunci yang tidak sah dibalas 401, dan kunci sah yang kekurangan scope dibalas 403 — keduanya perlu ditangani berbeda: 401 berarti kunci Anda perlu diperbaiki atau dirotasi, 403 berarti kunci Anda benar tetapi belum diberi akses ke endpoint itu.

json

// 401 — header X-API-Key tidak ada, salah, dicabut, atau kedaluwarsa
{ "status": false, "message": "API key tidak valid." }

// 403 — kunci sah, scope kurang
{ "status": false, "message": "API key Anda tidak memiliki scope \"sb:read\"." }

Status	Kapan
200	Berhasil
401	`X-API-Key` tidak ada / tidak valid / dicabut / kedaluwarsa
403	Kunci sah, tetapi tidak punya scope untuk endpoint itu
404	`id` tidak ditemukan, atau endpoint tidak dikenal
422	Parameter tidak valid — lihat `errors[]`
429	Melebihi batas permintaan — lihat header `RateLimit-Reset`
500	Kesalahan server; `message` berisi teks umum

Selalu periksa field status, bukan hanya kode HTTP.

Catatan untuk konsumen API

Paginasi

Default per_page adalah 20. Untuk menarik seluruh data, ulangi permintaan sampai pagination.has_next bernilai false — jangan menebak dari total_pages saja bila data bisa berubah di tengah penarikan.

Urutan

Selalu berdasarkan nama, bukan tanggal daftar. Karena itu paginasi offset bisa melewatkan atau menggandakan satu baris bila ada anggota baru disetujui di tengah penarikan. Untuk sinkronisasi berkala, tarik ulang seluruh daftar alih-alih mengandalkan halaman terakhir.

Field yang bergantung scope

Penting

npwp dan latitude/longitude hanya ikut terkirim untuk kunci ber-scope data:sensitif. Field direktori (id, no_anggota, nama, wilayah_kerja, kjsb) stabil untuk semua kunci.

Batas pemakaian

Lihat bagian Autentikasi. Gunakan cache di sisi Anda — data direktori jarang berubah, dan menariknya tiap kali halaman dibuka hanya membebani kedua sisi sekaligus menghabiskan kuota Anda.

Menyimpan kunci

Taruh di variabel lingkungan atau secret manager, jangan di repositori. Bila kunci pernah ter-commit, anggap bocor dan minta rotasi.