Troubleshooting

Resolve common platform issues — Shopee token expiry, product sync failures, redemption errors, rate limiting, CORS, and database connectivity.

Diagnose platform issues

Most platform issues fall into a few categories: Shopee token expiry, product sync failures, redemption lookup errors, and connectivity problems. Use this guide to diagnose and resolve them quickly.

Shopee token expiry

Shopee access tokens expire periodically. If the worker is not running or tokens fail to refresh, API calls to Shopee will fail.

Product sync failures

Product sync depends on the worker, Redis, the Shopee API, and PostgreSQL. A failure at any stage can leave a sync pending, return no products, or produce a Shopee API error.

Redemption errors

Buyer redemption can fail or return warnings when the order cannot be found, the order status is not eligible, the product has no redemption URL, or the client has exceeded the request limit.

Issue	Cause	Resolution
Order not found	No shop has this order, or the order is too old	Verify the order ID and confirm that it belongs to a connected shop
Order not redeemable	The order status is not in the allowed list	The order must be `READY_TO_SHIP`, `PROCESSED`, `RETRY_SHIP`, `SHIPPED`, `TO_CONFIRM_RECEIVE`, or `COMPLETED`
`CONTACT_SELLER_REQUIRED`	No redemption URL is configured for the purchased item	Ask the seller to assign a URL through the admin dashboard or API
Rate limit exceeded	More than 20 requests from one IP address in one minute	Wait one minute, then retry

The redemption endpoint has an in-memory rate limit of 20 requests per IP per minute. The limit resets when the backend restarts.

CORS issues

If the admin dashboard or public portal cannot reach the backend, check the allowed frontend origins in the backend configuration.

Verify that ALLOWED_CORS_HOSTNAMES in backend/.env includes every frontend origin.
The admin dashboard typically runs at http://localhost:5173.
The public portal typically runs at http://localhost:5174.
Restart the backend after changing CORS settings:
```
docker-compose restart backend
```

Database connection issues

The backend requires a PostgreSQL connection. If PostgreSQL is unreachable, check the container status, connection values, and backend logs before running migrations.

Check that PostgreSQL is running:
```
docker-compose ps db
```
Verify PG_HOST, PG_PORT, PG_DATABASE, PG_USER, and PG_PASSWORD in backend/.env.
The database container exposes port 5432 internally and maps to host port 5435.
Check backend logs:
```
docker-compose logs backend
```
If the database schema is not initialized, run migrations:
```
docker-compose --profile migrate up -d migrate
```

Redis connection issues

The worker and BullMQ queue depend on Redis for job scheduling and processing. A Redis connection failure prevents token refresh and product sync jobs from running.

Check that Redis is running:
```
docker-compose ps redis
```
Verify REDIS_HOST and REDIS_PORT in backend/.env.
Redis maps to host port 6379.
Check worker logs for Redis connection errors:
```
docker-compose logs worker
```

For sync behavior, see Product sync. For token management, see Seller shop management. For the buyer flow, see Buyer redemption.

Was this page helpful?