2.3 KiB
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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
- Cek Laravel log:
docker exec geonet-console tail -100 storage/logs/laravel.log - Cek container:
docker logs geonet-console --tail 50 - Jangan retry lebih dari 3x dengan exponential backoff.
Retry policy: Max 3x, backoff: 1s → 2s → 4s.