Troubleshoot the Supabase-to-Brails diagnostic

Find the failing stage without exposing credentials or weakening the account’s controls. The helper separates configuration, IP echo and Brails sandbox work so you can investigate the narrowest relevant part of the route.

Start with the exact helper result, the function revision and the environment. Keep the full proxy URL, Brails token and wallet response bodies out of logs and tickets.

Read the helper’s result correctly

The stage errors deliberately hide the underlying transport exception. A stage identifies the part of the helper that failed, not a complete root-cause diagnosis. The original helper does not report a distinct timeout, TLS or proxy-authentication error classification.

Configuration failure

Check required settings in the deployed function

The helper reads QUOTAGUARD_PROXY_URL and QUOTAGUARD_EXPECTED_IPS for either mode. wallets also requires BRAILS_SANDBOX_API_KEY before any fetch is attempted. Confirm the correct Supabase project has those values. Do not print the values to prove they exist.

Check the exact variable names. The general QuotaGuard guide uses other example names in places; this helper only reads the three names above. A similarly named secret does not satisfy the check. Follow Supabase’s secret-setting guidance for hosted configuration.

Check the proxy URL shape

The parser requires:

• http: or https: as the scheme.
• A hostname ending in .quotaguard.com.
• A username and password in the URL.
• No path other than /, and no query or fragment.

Use the subscription’s complete dashboard URL. Do not paste a bare IP address, a website URL, a SOCKS endpoint or a custom proxy hostname into this helper without a deliberate adaptation review. Credentials containing special characters must retain their proper URL encoding. The helper decodes the parsed username and password once before passing them to proxy authentication.

If the URL parses but client creation is unavailable or fails, the error still belongs to the configuration stage. Confirm the deployed runtime supports the selected Deno HTTP client configuration. A Node syntax check alone cannot establish that runtime capability.

Check the expected addresses

The helper requires exactly two distinct IPv4 values after trimming whitespace. A duplicate address, a third value, an empty value, an IPv6 literal or an octet above 255 is rejected. Copy the pair from the same subscription as the connection URL. Avoid using documentation example addresses as live configuration.

IP echo failure

The echo request never completes successfully

The cause could be proxy reachability, proxy authentication, the selected transport, destination access, TLS, a timeout or an unexpected response. Investigate with authorized runtime and provider tooling while keeping credentials redacted.

A proxy authentication failure is different from Brails authorization. If trusted tooling specifically identifies a proxy 407, start with the proxy credentials and connection URL. The helper itself may surface a proxy handshake failure only as its sanitized stage exception; do not expect every proxy error to appear as an ordinary response status.

Keep the actual dashboard scheme and port paired. For HTTPS destinations, Static and Shield differ on the outer connection. Switching a URL’s scheme without switching to the correct endpoint can create a protocol mismatch.

Do not disable certificate verification to make a TLS failure disappear. Confirm the host, deployment trust configuration and supported protocol instead.

The echo returns a different IP

The helper rejects the result and does not send the Brails key. Check that:

1. The connection URL and expected pair belong to the same subscription.
2. You are inspecting the same project and deployment revision that ran the check.
3. The secret values are not stale after a route change.
4. The returned response is the documented echo JSON shape.

Do not add an unexpected address to Brails just because it appeared in a failed diagnostic. First establish the authorized route and why the expected pair differs.

The response is not parseable JSON

An HTML error document, a redirect or another unexpected response is not an acceptable routing result. The helper rejects redirects and requires an ip property matching the expected pair. Investigate the selected proxy and echo destination rather than removing validation.

One address appears every time

This is not sufficient evidence of broken failover. The two-address design allows either source; repeated requests do not guarantee a particular distribution. Keep both approved. A controlled failover exercise needs a separately planned procedure and evidence, not a loop that assumes the next request must use the other address.

Echo succeeds but Brails access does not

Distinguish helper errors from HTTP error responses

A thrown Brails sandbox stage error means the helper did not return a usable final result. A returned brailsHttpOk: false means an HTTP response was received. Treat those as different observations in your incident notes.

In either case, an echo success proves only the echo route. The Brails connection has its own destination, provider policy and possible source selection. Obtain destination-side evidence where available.

Check environment and account pairing

The helper’s destination is fixed to:

https://sandboxapi.onbrails.com/api/v2/wallets

Use an authorized sandbox key for that account. A production key, another company’s sandbox key or a stale key is not a substitute. Brails documents environment-specific credentials and separate API base URLs.

Do not convert this diagnostic to production by changing its URL during troubleshooting. Keep a small, known sandbox check and review the production application separately.

Check the account’s source-IP policy

Confirm both allocated addresses appear in the appropriate account/environment when allowlisting is enabled. Verify the selected source region and shared or dedicated address type are acceptable for the account. Do not assume that a supported payout country answers those networking questions.

A returned 401 or 403 alone does not prove the root cause is IP rejection. It can require authentication or account-policy investigation. The linked Brails documentation does not justify an invented one-to-one error map for this helper.

Handle rate or service failures without creating a retry storm

If authorized evidence identifies rate limiting or a provider service problem, follow the provider’s guidance and your application’s retry policy. The helper does not retry. Repeatedly rerunning it at high frequency creates more traffic without establishing the original cause.

For a production money-moving operation, determine transaction state before retrying. This packet intentionally uses a read diagnostic so network investigation does not create a second payment.

Verify production clients after a successful sandbox read

The wallet endpoint is a read. This helper cancels its body and reports HTTP-level status only. It does not parse the provider’s business response, validate a payout, confirm settlement, or establish the source seen by Brails.

If the helper succeeds but the application fails, inspect the failing application’s actual client. It may use a separate SDK, an unconfigured background job, a direct fetch or a different environment. Compare call-site configuration rather than adding more retries to the successful helper.

Collect a useful private support record

Include only what is needed:

• UTC timestamp and environment label.
• Supabase function/deployment revision.
• Helper mode and the sanitized error stage or returned status.
• HTTP or HTTPS proxy transport and the subscription label.
• Whether the echo address matched the configured pair.
• Whether both addresses are approved for the relevant Brails account.
• Any request reference already available from provider-side records.

Omit secrets, the complete connection URL, raw request headers, wallet data and customer information. If provider-side source evidence is unavailable, say that the source Brails observed remains unconfirmed. Do not substitute the echo IP for that missing observation.

For the normal setup sequence, return to the quickstart or technical guide.

Download the reference examples · Integration overview