Troubleshooting

EN

API returns 401/403 unexpectedly

- Confirm guard and middleware path for target endpoint (auth:web, auth:sanctum, membership, role, permissions). - Verify route group placement before debugging controller logic.

Evidence pointers: - routes/api/admin/v1.php:52 - routes/api/mobile/v1.php:66 - routes/api/mobile/v1.php:132 - app/Http/Kernel.php:72 - app/Http/Kernel.php:73

OTP request gets throttled

- OTP uses dedicated limiter (Limit::perMinutes(10, 5)) and route throttle middleware. - Validate caller IP behavior in proxy/load balancer scenarios.

Evidence pointers: - app/Providers/RouteServiceProvider.php:70 - routes/api/mobile/v1.php:166

Chat endpoints fail on Firestore initialization

- Chat read routes are wrapped in init-firestore middleware. - Confirm FIREBASE_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS resolves to a readable service account file.

Evidence pointers: - routes/api/mobile/v1.php:89 - routes/api/admin/v1.php:229 - config/firebase.php:53

Queue jobs not processing

- Ensure queue worker services are running (customa-queue, customa-queue-pos-sync). - Validate deployment script completed docker compose up -d and did not fail earlier in SSM fetch phase.

Evidence pointers: - deploy/production/compose.yml:15 - deploy/production/compose.yml:30 - deploy/scripts/deploy.sh:83 - deploy/scripts/deploy.sh:10

API docs route unavailable

- API docs routes depend on explicit APIDocController::registerRoute(...) declarations in route files.

Evidence pointers: - routes/api/admin/v1.php:46 - routes/api/mobile/v1.php:170

ID

API tiba-tiba 401/403

- Cek guard dan middleware endpoint target (auth:web, auth:sanctum, membership, role, permissions). - Verifikasi posisi route group sebelum debug logic controller.

Evidence pointers: - routes/api/admin/v1.php:52 - routes/api/mobile/v1.php:66 - routes/api/mobile/v1.php:132 - app/Http/Kernel.php:72 - app/Http/Kernel.php:73

Request OTP terkena throttle

- OTP memakai limiter khusus (Limit::perMinutes(10, 5)) dan middleware throttle di route. - Validasi perilaku IP caller pada skenario proxy/load balancer.

Evidence pointers: - app/Providers/RouteServiceProvider.php:70 - routes/api/mobile/v1.php:166

Endpoint chat gagal saat inisialisasi Firestore

- Route baca chat dibungkus middleware init-firestore. - Pastikan FIREBASE_CREDENTIALS atau GOOGLE_APPLICATION_CREDENTIALS mengarah ke file service account yang bisa dibaca.

Evidence pointers: - routes/api/mobile/v1.php:89 - routes/api/admin/v1.php:229 - config/firebase.php:53

Queue job tidak jalan

- Pastikan service worker berjalan (customa-queue, customa-queue-pos-sync). - Validasi script deploy benar-benar mencapai docker compose up -d dan tidak gagal sebelumnya saat fetch SSM.

Evidence pointers: - deploy/production/compose.yml:15 - deploy/production/compose.yml:30 - deploy/scripts/deploy.sh:83 - deploy/scripts/deploy.sh:10

Route dokumentasi API tidak tersedia

- Route dokumentasi API bergantung pada deklarasi APIDocController::registerRoute(...) di file route.

Evidence pointers: - routes/api/admin/v1.php:46 - routes/api/mobile/v1.php:170