GUIDE

Troubleshooting

The problems people actually hit, and the one-line fix for each.

It won't start

Run it in the foreground and read the error. The message tells you what is wrong:

bash

python app.py

Error: "Address already in use"

Something else is already listening on port 8000 — usually another instance of the API, or a process manager (pm2) started it for you.

bash

ss -tlnp | grep 8000   # who owns the port?

If it is a pm2 process, stop it instead of running a second copy:

bash

pm2 list                # find the process name
pm2 stop payment-api    # then run python app.py yourself

Or use a different port for your manual run:

bash

PORT=8001 python app.py

Error: "SECRET_KEY and API_TOKEN are required"

The API cannot find your .env file, or the values are empty. Check:

.env exists in the project directory — ls -la .env
Both SECRET_KEY and API_TOKEN have values — cat .env
python-dotenv is installed — pip show python-dotenv. If missing: pip install -r requirements.txt

Without python-dotenv, the API silently skips loading .env and exits with this error even though the file looks fine. This is the most common cause.

Error: "ModuleNotFoundError: No module named 'X'"

Dependencies are not installed. Install them:

bash

pip install -r requirements.txt

If you used a virtual environment earlier, activate it first — a bare python may point at a different interpreter than the one with packages installed.

HTTP errors

Code	Body	Fix
`400`	`{"error": "coin must be BTC or LTC"}`	Send `"coin": "BTC"` or `"LTC"` — case-insensitive, quoted.
`400`	`{"error": "amount must be a number"}`	Send `amount` as a number, not a string: `5.0` not `"5.0"`.
`401`	`{"error": "invalid token"}`	The `Authorization: Bearer <token>` header is missing or wrong. Copy the token exactly from `.env`.
`404`	`{"error": "order not found"}`	Wrong order id, or it never existed. Check `GET /orders`.
`404`	`{"error": "unknown address"}`	Webhook address does not match any order. Copy the address exactly from the order.

Still stuck?

Every error response is JSON with an error field. The message is specific — read it before changing anything.

Payments not detected

The poller checks every 30 seconds. If a real payment is not showing up:

Wait a bit — up to 30 seconds between polls, plus confirmation time.
Check the address — the customer must pay the exact address from the order. One address per order; never reuse.
Confirmations — BTC needs 3 confirmations by default. The order stays pending until then. Check the transaction on a block explorer.
Network errors — the monitor prints [monitor] pass failed: ... in the API's terminal. BlockCypher rate limits free accounts to 3 requests/second; a BLOCKCYPHER_TOKEN in .env raises that.

Lost SECRET_KEY?

Private keys in the database are encrypted with SECRET_KEY. If you lose it, stored secrets are unrecoverable — there is no backdoor. If this happens:

Export any paid order keys before changing SECRET_KEY — the running API still has the old key in memory.
Back up .env together with payments.db — one is useless without the other.

This is by design: the server never stores keys in a form it can decrypt without your secret.