Kobaru
  1. Transparent Proxy
Kobaru
  • Kobaru.io Gateway API
    • Introduction
      • What is Kobaru?
      • Quick start
      • How x402 works
    • Integration
      • Standard x402 SDK
      • Advanced SDK
      • Transparent proxy integration
      • Direct API integration
    • Core Concepts
      • Available Chains and Assets
      • Payment schemes
      • Security
      • Usage models
    • Guides
      • Pricing your API
      • Going to Production
      • Testing with devnet
      • Bazaar discovery
    • API Reference
      • Error Handling
      • Get Supported Payment Kinds
      • Verify Payment Authorization
      • Settle Payment
    • Discovery
      • List Discovery Resources
    • Transparent Proxy
      • Overview - Transparent Proxy
      • Upstream authentication
      • Troubleshooting
      • Constraints and security
      • Capabilities and routes
      • Domain verification
      • Service setup
    • Schemas
      • SupportedResponse
      • ErrorResponse
      • UnauthorizedResponse
      • RateLimitResponse
      • VerifySuccessResponse
      • VerifyErrorResponse
      • SettleSuccessResponse
      • SettleErrorResponse
      • DiscoveryResourceItem
      • ListDiscoveryResourcesResponse
  1. Transparent Proxy

Troubleshooting

Common issues with the transparent proxy and how to fix them.

Domain verification#

DNS TXT verification keeps failing#

Check DNS propagation:
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:
If this fails:
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 after 7 days. Delete the domain in the Console and add it again to get a fresh token.

Service creation#

"Base URL must use a verified domain"#

The base URL domain hasn't been verified yet.
Fix:
1.
Go to Proxy > Domains
2.
Add and verify the domain
3.
Then create the service
Subdomains are automatically covered. Verifying example.com allows api.example.com.

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:
1.
Edit the service
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:
Wallet address
Default amount
Usage model
Usage limit
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.
Fix:
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#

Common causes:
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
4.
SSRF protection triggered - The target URL was blocked by the security rules

Request body too large#

The proxy enforces a 64KB maximum request body size. If your API needs larger payloads, use the Standard SDK instead.

Missing headers in forwarded requests#

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)

Usage runs out too quickly#

Check your usage model configuration:
Pay-per-request: Each successful (2xx) response consumes one request
Pay-per-time: All requests are allowed until the timer expires
Requests that return errors (5xx, 401, 403, 429) are not counted against the usage limit for pay-per-request.

Payments not showing in wallet#

Settlements happen on-chain. Depending on the network:
Solana: Sub-second finality
Base: ~2 seconds
SKALE: ~1 second
Check the transaction hash on the block explorer for your network.

Getting help#

If you can't resolve the issue:
Email: support@kobaru.io
When contacting support, include:
1.
Your service slug
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-02-10 21:51:00
Previous
Upstream authentication
Next
Constraints and security
Built with