Secure and retry API requests

Send Tango API requests from your server and retry order requests without creating duplicate rewards.

This guide covers request content, timeouts, rate limits, and order idempotency. To set up authentication, see Use Basic Auth to connect Tango API or Use OAuth for more secure connection. For credential storage and rotation, see Manage API credentials.

Before you begin

• Set up a server-side integration using Basic Auth or OAuth 2.0. Authenticate each request; Tango does not support browser-based API calls.
• Identify where your application assigns an externalRefID (your own reference for an order) so it can retain that value if the order request must be retried.
• Set your HTTP client timeout to wait at least 15 seconds for a response.

Send and retry requests

1. Send authenticated requests from your server: Do not put API credentials in browser code or call the Tango API directly from a browser. Browser-based calls can produce authorization error 403.001 or Cross-Origin Resource Sharing (CORS) errors; CORS is a browser security mechanism that controls requests to a different domain. The browser restriction is not limited to POST requests. If you see a CORS error, check whether your application is calling Tango directly from the browser.
2. Check request content: Validate values before sending them. Tango may reject content or behavior it identifies as potentially exploitative, including injection-style input. For POST operations, do not rely on HTML input being preserved: Tango escapes HTML input. See OWASP: Injection for background.
3. Assign a unique externalRefID to each order transaction: Include it when you create an order. Reuse the same value when retrying that transaction; use a new value for a different transaction. Tango enforces externalRefID idempotency at the account level: a repeat request for the same account and ID returns the original order rather than creating another, even if other order details change. The ID can contain up to 100 alphanumeric characters.
4. Wait for the response before deciding to retry: Configure the client timeout for at least 15 seconds on the initial request and on every retry. A timeout, connection loss, or 5XX response does not prove that an order was not placed; an order may still process after the connection is lost. Retry the same transaction with its original externalRefID.
5. Respect rate limits and increase the wait between retries: The order endpoint has a 1 transaction per second limit. If an order request receives a rate-limit error, wait at least one second before retrying with the same externalRefID. Use exponential backoff or another increasing-delay strategy for subsequent attempts rather than sending repeated requests immediately.

Check the result

• 201 Created: A new order was created. Save the returned referenceOrderID to track it.
• 200 OK for a reused externalRefID: Tango returned the existing order for that account; do not treat it as a second order. Check the returned referenceOrderID before continuing your workflow.
• 429 Too Many Requests: Reduce your request rate, wait, and retry an order with the same externalRefID.
• Timeout, connection loss, or 5XX: Do not assume the order failed. Retry the same transaction with the same externalRefID and check the response before creating a new transaction.
• Request validation or authentication error: Inspect the error and correct the request or credentials before sending it again. See Response classes and error messages.

If you omit externalRefID, the response header X-REQUEST-ID can help Tango support locate the transaction, but it does not provide the same duplicate-order protection on retries. For more on account-scoped idempotency and response handling, see Best practices.