# Error Guide — geonet-console API

Panduan lengkap untuk menangani error. AI Agent tidak boleh menebak — ikuti panduan ini.

---

## 401 Unauthorized

**Kondisi:** Token tidak ada, tidak valid, atau expired.

**Solusi:**
- JWT expired → Login ulang ke `POST /api/v1/auth/login`
- API Token salah → Cek token di `/api-clients`
- Header tidak ada → Pastikan format `Authorization: Bearer <token>`

**Contoh response:**
```json
{
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Unauthenticated."
    }
}
```

**Retry:** Tidak boleh retry dengan token yang sama. Harus dapatkan token baru.

---

## 403 Forbidden

**Kondisi:** Token valid tapi tidak memiliki scope yang diperlukan.

**Solusi:** Minta admin tambahkan scope yang diperlukan pada API Token di `/api-clients`.

**Contoh response:**
```json
{
    "error": {
        "code": "FORBIDDEN",
        "message": "Insufficient scope. Required: ldap:write"
    }
}
```

**Retry:** Tidak perlu retry. Masalah ada di permission, bukan token.

---

## 404 Not Found

**Kondisi:** Resource tidak ditemukan (ID salah, sudah dihapus).

**Contoh response:**
```json
{
    "error": {
        "code": "NOT_FOUND",
        "message": "Service token not found"
    }
}
```

**Retry:** Tidak perlu retry. Verifikasi ID yang digunakan.

---

## 422 Unprocessable Entity

**Kondisi:** Data request tidak lulus validasi.

**Contoh response:**
```json
{
    "message": "The given data was invalid.",
    "errors": {
        "name": ["The name field is required."],
        "expires_in_days": ["The expires in days must be at least 1."]
    }
}
```

**Retry:** Tidak perlu retry. Perbaiki data request sesuai pesan error.

---

## 429 Too Many Requests

**Kondisi:** Melebihi rate limit.

| Endpoint | Rate Limit |
|----------|------------|
| `POST /auth/login` | 10 request / menit |
| `POST /project-search/ask` | 20 request / menit |

**Contoh response:**
```json
{
    "message": "Too Many Attempts."
}
```

**Retry:** Tunggu 60 detik sebelum retry. Cek header `Retry-After`.

---

## 500 Internal Server Error

**Kondisi:** Error di sisi server (bug, DB down, dll.).

**Solusi:**
1. Cek Laravel log: `docker exec geonet-console tail -100 storage/logs/laravel.log`
2. Cek container: `docker logs geonet-console --tail 50`
3. Jangan retry lebih dari 3x dengan exponential backoff.

**Retry policy:** Max 3x, backoff: 1s → 2s → 4s.