Troubleshooting

Quick fixes for common issues and understanding system fallbacks.

401 Unauthorized Error

Symptom: Your API calls to /api/recommend return a 401 status code.
Solution: Verify that your Authorization header includes Bearer <YOUR_API_KEY>. Ensure the API key hasn't been revoked or deleted in your dashboard. Check that the merchant_id in the JSON payload matches the merchant ID associated with the key.

Receiving Generic Recommendations (Fallback)

Symptom: The AI always suggests the same two popular items and the response shows "source": "fallback".
Solution: This happens when the AI "Circuit Breaker" trips. It usually means:
  • The AI API took longer than 1.2 seconds to respond (Timeout).
  • Your menu inventory is empty (Ensure you have products in My Menu).
  • The AI hallucinated a product ID that doesn't exist in your catalog (Zero-hallucination validation).
The system successfully protected your checkout flow from freezing. Check your Dashboard logs for the exact error reason.

Product not showing in Cashier Screen

Symptom: You added a product in the Menu page but it doesn't appear in the cashier screen.
Solution: Make sure the product is marked as Active in the Menu page (toggle the switch). Only active products appear in the cashier and kiosk. If the product is active, try refreshing the cashier page — it caches products for offline use.

Insufficient Stock Error on Checkout

Symptom: Checkout returns a 409 error with "Insufficient stock".
Solution: The product's stock tracking is enabled and the available quantity is lower than the sale. Go to the Menu page and restock the product, or disable stock tracking for that product if inventory management is not needed.