Troubleshoot proxy and middleware requests

When requests to the Tango API pass through a proxy, middleware service, or API gateway, a 403 Forbidden response can occur if the proxy modifies or injects forwarding headers.

A common cause is the X-Forwarded-For (XFF) header. Some proxies append the client IP address along with a source port (for example, 203.0.113.10:54321). Tango's AWS Application Load Balancer expects IP-only values in the X-Forwarded-For header. If the header contains an IP address with a port suffix, the request may be rejected before it reaches the Tango API.

Before changing proxy configuration, first determine where the 403 response is being generated. A 403 can result from multiple causes, and not all are related to forwarding headers. Verify whether the response originates from your proxy, gateway, load balancer, or the Tango API itself.

Before you begin

• Send requests from a server-side integration authenticated with Basic Auth or OAuth 2.0, not from browser code.
• Capture the response status, headers, and body, and inspect the outbound headers that your proxy sends to Tango. Redact credentials before sharing logs or request captures.
• Check which Tango environment your proxy calls: sandbox (integration-api.tangocard.com) or production (api.tangocard.com). If your platform uses mTLS, check its dedicated host instead.

Investigate a 403

1. Identify the responding layer. Inspect the response body and Server header. An HTML response with awselb/2.0 can indicate that the load balancer rejected the request before the Tango API handled it; a JSON API error calls for investigation of its reported cause. These are diagnostic clues, not proof of a specific misconfiguration.
2. Inspect the outbound XFF header. Capture the request after your proxy or gateway has added headers. X-Forwarded-For must contain IP-only values without a port suffix. For example, 203.0.113.42:54321 contains a port and may trigger an infrastructure-level 403; 203.0.113.42 does not contain a port. Do not log or share the Authorization header or other secrets.
3. Correct a malformed header at the proxy. If XFF contains an IP and port, configure the component sending the request to remove the port, replace the header with an appropriate IP-only value, or remove it where your proxy permits. Verify the resulting outbound header rather than assuming an inbound-header change affects what Tango receives.
4. Retry the same authenticated request. Confirm that the revised request reaches the API. An API response other than 200 can still show that the request passed the load balancer; check its error details separately. Do not assume a header fix also resolves authentication, allowlist, or request-validation errors.

Correct the header in your middleware

Choose the change supported by the component that sends the outbound request:

For example, an Azure outbound policy can override the header once you have verified the public IP value to send:

<set-header name="X-Forwarded-For" exists-action="override">
    <value>{{YOUR_OUTBOUND_PUBLIC_IP}}</value>
</set-header>

Replace the policy variable with your configured, verified public IP value. Test the policy in sandbox and capture the outbound header to confirm that it no longer includes a port. The expected result is an IP-only XFF value; the HTTP status still depends on authentication and the request itself.

If the 403 continues

• XFF is IP-only, but the response is an HTML load-balancer error: Recheck the final outbound headers, including headers added by downstream middleware. If the cause remains unclear, provide Tango support with the request time and a redacted response for investigation.
• The API returns an authentication error: Confirm the Basic Auth credentials or OAuth token are valid for the target environment and that the token has not expired. See Manage API credentials for OAuth token lifetimes.
• The error identifies an IP restriction: Determine the proxy’s public egress IP as seen by Tango. If your platform has an IP allowlist, that IP must be approved; see Restrict access with an IP allowlist and contact your Tango representative to update entries.
• The request originates in a browser: Move the API call to a trusted server-side environment. Browser-based requests are not supported and may produce authorization or Cross-Origin Resource Sharing (CORS) errors.
• The request uses the wrong host: Verify sandbox versus production and, if mTLS is enabled, use its dedicated endpoint.

If you need help isolating the rejection, contact your Tango representative or [email protected] with the environment, timestamp, response details, and redacted outbound headers.