---
title: "Kode Error & Pemecahan Masalah"
summary: "Daftar lengkap kode error beserta penyebabnya, kebijakan percobaan ulang, dan jawaban untuk masalah yang paling sering muncul."
slug: developer-api-error
product: LENSIRO
source: https://lensiro.com/dokumentasi/developer-api-error
updated: 2026-08-23
---

# Kode Error & Pemecahan Masalah

> Daftar lengkap kode error beserta penyebabnya, kebijakan percobaan ulang, dan jawaban untuk masalah yang paling sering muncul.

## Bentuk error

Semua error memakai bentuk yang sama:

```json
{ "error": { "code": "invalid_limit", "message": "limit must be an integer between 1 and 500." } }
```

Gunakan `error.code` untuk logika program. `error.message` ditujukan untuk manusia dan kata-katanya bisa berubah.

## Daftar lengkap kode error

| HTTP | `code` | Penyebab | Cara memperbaiki |
|---|---|---|---|
| 400 | `invalid_limit` | `limit` bukan bilangan bulat 1–500 | Pakai nilai 1–500 |
| 400 | `invalid_date` | Parameter tanggal tidak bisa dibaca | Pakai ISO 8601, contoh `2026-08-13T00:00:00Z` |
| 400 | `invalid_parameter` | Angka negatif atau pecahan, atau nilai enum di luar daftar | Cek tipe dan daftar nilai di **Referensi Endpoint** |
| 400 | `invalid_cursor` | `cursor` rusak atau bukan berasal dari respons API | Jangan ubah cursor; kalau ragu, mulai lagi tanpa cursor |
| 400 | `invalid_id` | `{id}` di path bukan bilangan bulat minimal 1 | Periksa URL yang dibentuk program Anda |
| 401 | `missing_api_key` | Header `Authorization` tidak ada atau salah bentuk | Kirim `Authorization: Bearer lsk_live_...` |
| 401 | `invalid_api_key` | Key tidak dikenal atau tidak diawali `lsk_` | Pastikan key tersalin utuh |
| 401 | `revoked_api_key` | Key sudah dicabut | Buat key baru di **Pengaturan → API Key** |
| 401 | `expired_api_key` | Key sudah kedaluwarsa | Buat key baru |
| 404 | `not_found` | Objek tidak ada, atau sudah dihapus | Endpoint per-id tidak melayani data terhapus |
| 429 | `rate_limited` | Melebihi 60 request per menit per key, atau 120 per menit per IP | Tunggu sesuai `Retry-After` |
| 500 | `internal_error` | Kesalahan di sisi server | Coba ulang dengan jeda bertingkat; kalau terus terjadi, hubungi tim Lensiro dengan URL dan waktunya |

Metode selain `GET` dijawab `405` tanpa body error.

## Kebijakan percobaan ulang

| Status | Boleh diulang? | Cara |
|---|---|---|
| 400, 401, 404 | Tidak | Perbaiki request atau key dulu — mengulang akan gagal lagi |
| 429 | Ya | Tunggu sebanyak detik di `Retry-After`, lalu ulangi request yang sama |
| 500 | Ya | Jeda bertingkat: 1 detik, 2, 4, 8, maksimal lima kali |
| Timeout jaringan | Ya | Aman — semua endpoint hanya membaca, jadi mengulang tidak mengubah apa pun |

## Pemecahan masalah

### Semua request dijawab 401 padahal key baru dibuat

Urut dari yang paling sering: ada spasi atau baris baru ikut tersalin; kata `Bearer` hilang atau tanpa spasi; key ditaruh di query string, yang tidak didukung; atau key sudah dicabut. Cek dengan `/ping` lebih dulu — kalau `/ping` berhasil tapi endpoint lain gagal, masalahnya bukan di key.

### `data` kosong padahal datanya jelas ada

1. **Zona waktu.** Filter tanggal memakai UTC. "Hari ini" di WIB dimulai pukul `17:00Z` hari sebelumnya. Ini penyebab nomor satu.
2. **Salah ketik nama parameter.** Parameter yang tidak dikenal diabaikan diam-diam, jadi `branch=2` (bukan `branch_id=2`) tidak menimbulkan error tapi juga tidak menyaring apa pun.
3. **Filter saling meniadakan**, misalnya `transaction_date_from` lebih besar daripada `transaction_date_to`.
4. **`updated_since` terlalu baru** karena checkpoint Anda sudah maju lebih dulu.

### Angka rekap saya beda dengan laporan di aplikasi

Periksa berurutan:

1. **Zona waktu** — laporan aplikasi memakai waktu lokal, API memakai UTC.
2. **Transaksi batal** ikut terkirim secara default. Buang `status = "CANCELED"` kalau laporan pembanding tidak menghitungnya.
3. **Kolom yang dibandingkan** — `total` (sebelum klaim asuransi) tidak sama dengan `net_total` (setelah klaim asuransi).
4. **Uang masuk vs omzet** — `/sales/payments` dikelompokkan per tanggal bayar, `/sales` per tanggal order. Untuk transaksi yang dicicil, keduanya memang berbeda.
5. **Paginasi berhenti terlalu cepat** — pastikan loop berjalan sampai `has_more` bernilai `false`.

### Ada transaksi yang masuk dua kali ke sistem saya

Sistem Anda melakukan *insert*, bukan *upsert*. Ini memang harus ditangani: `updated_since` bersifat inklusif dan sengaja mengirim ulang baris di batas waktu, ditambah baris yang berubah saat paginasi berjalan. Kuncinya `id` — untuk pergerakan stok, `id` yang berbentuk string.

### Transaksi yang dihapus tidak pernah hilang dari sistem saya

Anda belum memakai `include_deleted=true`. Tanpa itu, data terhapus berhenti terkirim tanpa penanda apa pun, dan salinan Anda tidak pernah tahu.

### Stok di API tidak cocok dengan aplikasi

Cek `as_of` di respons — kalau snapshot Anda sudah lama, tarik ulang. Kalau masih beda, lihat bagian **Rekonsiliasi** di halaman **API Gudang**; penyebab yang paling sering adalah rentang tanggal pergerakan yang memotong sebagian riwayat.

### Barang sudah dikirim antar cabang tapi `TRANSFER_IN` belum muncul

Memang begitu perilakunya: `TRANSFER_IN` baru tercatat setelah cabang tujuan mengonfirmasi penerimaan di aplikasi. Selama barang di perjalanan, stok berkurang di cabang asal dan belum bertambah di cabang tujuan.

### Saldo poin pelanggan tidak pernah diperbarui

Perubahan poin tidak mengubah `updated_at` pelanggan, jadi polling `updated_since` tidak akan mengirimnya ulang. Poll `/members/{id}/point-logs`, atau lakukan full refresh `/members` secara berkala.

### Backfill kena `429` terus

Tarik per rentang bulanan, satu halaman pada satu waktu, dan beri jeda sekitar satu detik antar request. Menaikkan `limit` ke 500 mengurangi jumlah request, tapi untuk `/sales` payload-nya jadi besar karena item dan pembayaran ikut menyatu — 100 sampai 200 biasanya paling seimbang.

### Responsnya lambat

Perkecil `limit`, dan persempit filter dengan `branch_id` atau rentang tanggal. `/warehouse/stocks` dan `/warehouse/stock-movements` paling berat karena dihitung ulang dari seluruh riwayat — jadwalkan di luar jam sibuk toko.

## Melaporkan masalah

Kalau masalahnya tampak berasal dari sisi Lensiro, kirimkan ke tim Lensiro: **URL lengkap** yang dipanggil (tanpa API key), **waktu kejadian** beserta zona waktunya, **kode status dan body error** yang diterima, serta nama key yang dipakai. Dengan itu kejadiannya bisa ditelusuri di log server.


---

Dokumentasi Lensiro · https://lensiro.com/dokumentasi/developer-api-error · diperbarui 23 Agustus 2026