> For the complete documentation index, see [llms.txt](https://trust-positif.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://trust-positif.gitbook.io/docs/guides/errors.md).

# Error handling

Semua error API mengembalikan JSON dengan `success: false` kecuali dinyatakan lain.

## Format umum

```json
{
  "success": false,
  "message": "Human-readable error message"
}
```

Field tambahan (opsional) menggambarkan limit:

* `rate_limit` — freemium harian
* `quota` — premium / paket
* `code` — kode error tambahan (jika ada)
* `whitelisted_ips` — daftar IP diizinkan (403 whitelist)

## HTTP status codes

| Status  | Arti                                    | Tindakan                             |
| ------- | --------------------------------------- | ------------------------------------ |
| **200** | Sukses                                  | Parse `results` / `limit`            |
| **401** | API key tidak valid                     | Periksa header `X-API-Key`           |
| **402** | Kuota paket habis                       | Upgrade / beli paket                 |
| **403** | IP tidak di whitelist                   | Tambah IP di dashboard               |
| **422** | Input invalid                           | Perbaiki body `domains`              |
| **429** | Limit harian/bulanan atau throttle HTTP | Backoff, kurangi batch, cek `/limit` |
| **500** | Kesalahan server                        | Retry dengan exponential backoff     |

## Retry strategy

```
Attempt 1 → immediate
Attempt 2 → wait 2s
Attempt 3 → wait 4s
Attempt 4 → wait 8s (max ~30s total)
```

Jangan retry **401**, **403**, **422** tanpa mengubah request.

Untuk **429**, baca `remaining` di body; jangan retry sampai reset harian atau kuota tersedia.

## Validasi client-side

Sebelum memanggil API:

1. Normalisasi domain (lowercase, buang scheme/path)
2. Dedupe daftar domain
3. Chunk per 100 domain per request
4. Premium: pastikan `domains.length × 3 ≤ quota.remaining`

## Logging

Log di sisi klien:

* HTTP status + `message`
* Jumlah domain dikirim
* `stats` / `limit` setelah error 429

Jangan log full API key — mask `tp_****`.