Response Classes

There are three HTTP status classes you are expected to encounter from time-to-time.

2xx Responses (Successful)

2XX responses indicate a successfully completed request.

4xx Responses (Request Error)

4XX errors are related to incorrect requests. These requests should be reviewed and corrected before retrying.

5xx Responses (System Error)

5XX errors indicate the Tango Card system cannot fulfill the request. This might be due to temporary issues with one of our suppliers, Tango Card's system or undetermined internet vagaries. Given the nature of HTTP-over-internet communications, 500 errors are inevitable and we strongly recommend implementing an exponential backoff retry mechanism that retries order requests when a 500 series error is received. Order requests receiving a 5XX error may occasionally process after a network connection is lost. The optional External Reference ID is an idempotent parameter that can be used to ensure duplicate orders are not created.

Other Responses

1XX series responses are not implemented at this time and are not expected
3XX series responses are not expected and should be reported to Tango Card immediately

Response Headers

Every response header will include useful date, including:

• date
• [ X-REQUEST-ID]

Consider logging these values for potential error troubleshooting; along with the response JSON:

• Order Reference ID for successful orders
• requestId, httpCode and message for errors

{
    "timestamp": "2021-09-20T14:52:56.8Z",
    "requestId": "492fc1a0-ae5b-441b-a12a-ff6c028ceded",
    "path": "/raas/v2/orders",
    "httpCode": 400,
    "httpPhrase": "Bad Request",
    "errors": [
        {
            "path": "utid",
            "code": 400500,
            "i18nKey": "422.024",
            "message": "The Item identifier provided is not valid. Please check the identifier and try again. You can confirm valid Items with the Get Catalog call."
        }
    ]
}

Response Handling Recommendations

Error responses include an i18nKey which provide a unique error code to facilitate international translations.

Error Testing in Sandbox

Tango Card has included two Items in our Sandbox environment that can be used for testing 5XX series errors. Placing an order for these items will result in the most common error responses you are likely to encounter in production.

🚧

If you do not see these items in your catalog, please contact your Tango Card CSM.