Debugging & pitfalls

Symptom: endless 402

• Missing or invalid payment-signature on retry — confirm the client sends the header name your middleware expects (case-insensitive in HTTP, but be consistent).
• Wrong facilitator URL — verify/settle must be reachable from your server, not the browser.
• Amount / network / payee mismatch — requirements in the 402 body must match what the client signed.

Symptom: verify passes, settle fails

• Check facilitator logs or response bodies for settlement errors (insufficient allowance, wrong chain, expired authorization).
• Ensure timeouts in your middleware are high enough for slow RPCs (@tallypay/server uses bounded fetch timeouts).

Symptom: CORS / cookies

• If the browser calls your API cross-origin, configure CORS for your API origin and avoid relying on cookies unless you control both sides.

Symptom: “works locally, fails in prod”

• HTTPS and mixed-content rules for wallet libraries.
• Environment variables for facilitatorUrl, payTo, and keys — use separate values for test vs mainnet.

Observability

• Add optional apiKey (server + client) so TallyPay can stitch 402_ISSUED → 402_RECEIVED → settlement into a single trace.
• Propagate x-trace-id from responses in your own logs for support tickets.

Security

• Never log raw payment signatures or secrets.
• Treat facilitator responses as untrusted input — map to your own error codes for clients.

If you want this list expanded with concrete error strings from your facilitator, suggest an edit once the docs repo is public—or reach out via tallypay.dev until then.