TunnelSats uses standard HTTP response codes. Since our API involves real-world Lightning transactions, understanding these codes is the difference between a smooth automation and a broken one.

📊 Common Status Codes

Code	Meaning	Common Cause in TunnelSats	Mitigation
400	Bad Request	Invalid `serverId` or missing `paymentHash`.	Check your request body JSON syntax.
401	Unauthorized	Missing or invalid `apiKey`.	Ensure your Bearer token is valid in the Header.
402	Payment Required	Subscription exists but hasn't been paid yet.	Poll the status until it returns `paid`.
404	Not Found	No subscription found for that `paymentHash`.	Ensure you are using the correct hash from the `/create` call.
429	Too Many Requests	You've hit the rate limit.	Slow down your polling! (Max 1 request every 5s).
503	Service Unavailable	Backend node is syncing or Tunnel-Bot is down.	Wait 30 seconds and try again.

🔍 Specific Scenarios

Invoice Expiration

Rate Limiting (429)

Cloudflare 403

402 vs. 404

If a user waits too long to pay, the invoice will expire.

Scenario: You poll and keep getting pending.

Action: If the expiresAt timestamp has passed, discard the current paymentHash and call /create again.

📝 Node Integration Checklist

For developers building integrations for Umbrel, Start9, or RaspiBlitz, follow this checklist to ensure a seamless user experience.

1. The Provisioning Flow

Server Selection: Use GET /servers to allow users to pick the region closest to them for lower latency.

In-App Payment: Display the BOLT11 invoice clearly. If the node OS has a built-in wallet, provide a "Pay Now" button that calls the local wallet API.

Polling UI: Provide a visual spinner or progress bar while polling GET /subscription/{paymentHash}.

2. Configuration Management

WireGuard Claim: Always offer a way to "Claim" the config again if the initial download fails.

File Persistence: Store the generated .conf file in a persistent directory that survives OS updates.

Custom Keys

We recommend generating keys on our server (leaving wgPublicKey empty) for the easiest setup. However, for maximum privacy, allow advanced users to provide their own wgPublicKey.

🛑 Error Codes & Troubleshooting

📊 Common Status Codes#

🔍 Specific Scenarios#

📝 Node Integration Checklist#

1. The Provisioning Flow#

2. Configuration Management#

📊 Common Status Codes

🔍 Specific Scenarios

📝 Node Integration Checklist

1. The Provisioning Flow

2. Configuration Management