Client APIs

# Issue recovery using idempotency

Version

This page is for the Client API v2. For the Client API v3 documentation, please see the issue vouchers page.

Please refer first to the Idempotency documentation.

# When to attempt recovery using idempotency?

Recovery should be attempted after failed Request Vouchers if the error response is not handled.

Recovery is especially expected when facing:

  • Timeouts and disconnections: timeouts and disconnections may occur at different steps of the issuance process including between the Client and the UNIQREWARDS API or internally in the Client's system. In such cases, vouchers may be issued in the UNIQREWARDS system and not received/recorder by the Client.
  • An unhandled API error (especially 500 Internal Server Error with ERV1102 or ERV1202 error codes): a failure occurred in the UNIQREWARDS system. Vouchers may have been issued and should be recovered using the idempotency ID. Infrequent errors like API timeouts (>10 seconds) will return ERV1102.

# Recovery process

# Initial voucher issuance request

The initial voucher issuance request follows the Request Vouchers documentation.

At this step, for eventual recovery, the header value X-Correlation-Id needs to saved in the Client's system along with the other request parameters.

# Request Headers



 




X-Client-Id: a1f64ebc9c4fef739df58f5933ceec94
X-Client-Secret: 1231f6112bbff1b03892306f53281bb0
X-Correlation-Id: f6dc536c-82fe-bccb-8639-9cb85a4eefcd
Authorization: Bearer 
77F309C43E153B286FE6BB1FBB2A901C15DDA9F619E82B4522EDE988B8C409CF
Content-Type: application/json

# An error occurred in the response / no response was received

No 200 OK response was received with vouchers details, a recovery attempt using the idempotency ID should be performed.

Tip

Any failed request with an error response can be safely repeated using the same X-Correlation-Id although known errors (incorrect credentials, product, etc.) should be handled by the Client's system.

# Recovery attempt

The request is identical to the initial one, including the X-Correlation-Id header value.

Note

A Recovery attempt is the only situation when a X-Correlation-Id value can be reused.

# Request Headers



 




X-Client-Id: a1f64ebc9c4fef739df58f5933ceec94
X-Client-Secret: 1231f6112bbff1b03892306f53281bb0
X-Correlation-Id: f6dc536c-82fe-bccb-8639-9cb85a4eefcd
Authorization: Bearer 
77F309C43E153B286FE6BB1FBB2A901C15DDA9F619E82B4522EDE988B8C409CF
Content-Type: application/json

# Recovery attempt response

The final response is received, it can be either:

  • a successful Request Voucher response with 200 OK and voucher details in the response body: the issue was recovered 👍.
  • a failed response with the same result/error received in the initial response. In such case:
    • if the initial error was a timeout or disconnection, further investigation needs to be done.
    • an API error response indicating that vouchers were not issued. The error response and message should be investigated.

Note

If you need assistance analyzing API errors or troubleshooting timeouts and disconnection, please refer to Troubleshooting and Support.

← Integration process and UAT →