Common issues with the transparent proxy and how to fix them.
Domain verification#
DNS TXT verification keeps failing#
If the record doesn't appear:1.
Wait for your DNS TTL to expire (use 300 seconds during setup for faster propagation)
2.
Make sure there are no trailing dots in the hostname
3.
Verify the value matches exactly - no extra quotes or spaces
4.
Some DNS providers require @ for apex domain records
HTTP file verification fails#
Check the file is accessible:1.
Confirm HTTPS is enabled (HTTP is not accepted)
2.
Check for redirects (301/302 can cause issues)
3.
Verify file permissions (the file must be publicly readable)
4.
Make sure the .well-known path doesn't require authentication
Verification token expired#
Tokens expire 7 days after you add the domain. Add the same domain again at Proxy > Domains to get a fresh token; the expired entry is replaced automatically. Then update your DNS record or verification file with the new token and verify again.
Service and route creation#
"Base URL must use a verified domain"#
The base URL domain hasn't been verified yet. The full message names the host that failed, for example Base URL must use a verified domain (api.example.com is not).2.
Add and verify the domain
Subdomains are automatically covered. Verifying example.com allows api.example.com. The reverse isn't true: verifying api.example.com doesn't cover example.com."Target URL must use a verified domain"#
A route's target URL follows the same rule as a service base URL: its host must be a domain you verified, or a subdomain of one. Verify the domain at Proxy > Domains, or point the route at a host on a domain you already verified.Slug collision#
Two merchants with different domains can generate the same slug (e.g., merchant-a.com and merchant-a.io both generate merchant-a).The system handles this automatically by falling back to the full domain with hyphens:merchant-a.com --> slug: merchant-a
merchant-a.io --> slug: merchant-a-io
Enterprise customers can choose and design their own custom slugs.Service shows "No base URL" warning#
This shouldn't happen for proxy-type services, but if it does:2.
Set a valid base URL using the console
3.
Make sure the domain is verified
Capabilities#
Capability shows "Needs config"#
The capability was enabled but not fully configured. All four fields are required:Go to Capabilities, click edit on the capability row, and fill in the missing fields."Capability not enabled" error from the gateway#
The network/scheme/asset combination hasn't been enabled for your account.1.
Go to Capabilities in the Console
2.
Enable the correct combination (e.g., Solana + Exact + USDC)
3.
Configure all required fields
Make sure you're using the right network identifier. For example:Production: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Devnet: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
Upstream authentication#
"Test Connection" fails#
1.
Verify your backend is running and accessible
2.
Confirm the base URL is correct
3.
Check that the API key is valid on your backend
4.
Make sure the health check endpoint exists (defaults to /health)
Requests reach backend without authentication#
If proxyAuthType is set to none (the default), no key is injected. Configure upstream authentication in the service edit dialog.Backend returns 401 after key rotation#
If you rotate the encryption key (PROXY_AUTH_ENCRYPTION_KEY) in the Console or Gateway without re-encrypting existing keys, decryption fails silently and the request proceeds without the auth header.Fix: After rotating the encryption key, re-save the API key for each affected service in the Console.
Request forwarding#
Backend returns 502#
1.
Your backend is down - Check that it's running
2.
Upstream timeout - The proxy has a 50-second timeout. If your backend takes longer, it times out
3.
Redirect blocking - The proxy blocks all 3xx redirects. If your backend redirects, resolve it before the proxy endpoint
Request body too large#
The proxy enforces a 64KB maximum request body size. If your API needs larger payloads, use the Standard SDK instead.The proxy strips Authorization and Payment-Signature headers before forwarding. If your backend expects an Authorization header, configure upstream authentication to inject it.
Payment issues#
Client gets 402 even after paying#
The payment may have failed verification. Common causes:Insufficient token balance
Transaction blockhash expired (transactions expire after ~150 seconds)
Wrong network (e.g., using devnet token on mainnet)
Check the reason in the 402 body:payment_expired: the payment was already settled and its quota has lapsed; a new payment is needed
payment_bound_to_other_route: the payment was first used on another route of your service; its quota belongs there
payment_proof_mismatch: the signature isn't the one the payment was verified with
payment_already_used: a single-use payment (limit 1) was already used
payment_settlement_failed: the settlement failed for good (reverted on chain, or expired before it landed); a new payment is needed
usage_exhausted: the quota is used up
Client gets 503 with Retry-After#
Not a payment failure. The client should retry after Retry-After and must not pay again.reason | Retry-After | Meaning |
|---|
settlement_pending | 30 | The settlement of this payment has an unknown outcome (transaction is included when known; check it on chain). Kobaru resolves it on the client's retry or in the background |
duplicate_request | 5 | The same payment is being processed right now by another request |
claim_unavailable | 5 | The payment couldn't be claimed right now (temporary database problem) |
server_configuration_error | 30 | The gateway can't process this payment network right now (server-side configuration). Nothing was broadcast |
unexpected_verify_error | 5 | Verification failed unexpectedly on the server |
rpc_unavailable | 5 | EVM: the network's RPC couldn't be reached while checking the payment against the token contract. Nothing was broadcast |
bite_unavailable | 10 | SKALE: the BITE encryption service is unreachable (error Payment encryption temporarily unavailable). Nothing was broadcast |
When a payment's settlement is unresolved, the next request with it doesn't reach your backend until the proxy has asked the chain: if the payment turns out settled, the request is served, and it doesn't cost a new use when your API already answered the request that got the 503 (single-use payments included). If it failed for good, the client gets 402 payment_settlement_failed. If the chain still can't tell, the client gets 503 again and your backend isn't called.If your backend answered 2xx but the settlement then ended with an unknown outcome, claim_unavailable, server_configuration_error, rpc_unavailable or bite_unavailable, the client gets 503 instead of your response. With all but settlement_pending the use is refunded (nothing was broadcast); with settlement_pending it is kept until the outcome is known.Several requests served while one payment settles#
While the first settlement of a payment is still running (up to about 65 seconds), other requests with the same payment that are within its quota are served normally, marked as still pending. This is intended: the payer is charged at most once, and the extra service is bounded by the payment's quota (at most limit − 1 more requests for pay-per-request, or the rest of the time window, up to about 65 seconds of it, for pay-per-time). If that settlement then fails, those requests were served without payment.Usage runs out too quickly#
Check your usage model configuration:Pay-per-request: each request consumes one use when it reaches your backend. What happens next depends on your response:2xx: consumed, and the payment is settled
401, 403, 429, 5xx: refunded, not settled
any other non-2xx (e.g. 400, 404, 422): consumed, not settled
Pay-per-time: the timer starts on the first request and all requests are allowed until it expires; nothing is refunded. The payment is settled on the first 2xx.
A request whose settlement ends with an unknown outcome (503 settlement_pending) is counted until the outcome is known, so a retry can't get your API for free while the payment is unresolved. Kobaru checks pending settlements on chain in the background, so the outcome is known even if the client doesn't retry right away. When the outcome turns out to be a success, the client's next request with the same payment is served without costing another use.One payment has one quota, whatever the encoding of its signature, and it belongs to the first route that used it.Payments not showing in wallet#
Settlements happen on-chain. Depending on the network:Solana: Sub-second finality
Check the transaction hash on the block explorer for your network.
Getting help#
If you can't resolve the issue:When contacting support, include:2.
The error message or HTTP status code
3.
The timestamp of the failed request
4.
Whether this is a new issue or a regression
Modified at 2026-10-30 21:41:55