Idempotency

Solvimon supports idempotency which allows for requests to be retried while ensuring only one of those requests will take effect. This means that when using idempotency, the API will not perform the same operation more than once when the same request is sent. In the scenario where a connection error occurs, the request can be repeated, knowing that there is no risk of performing the same operation again.

How the Idempotency-Key is generated is up to the sender. Solvimon advises using V4 UUIDs, or any other method such that collisions of keys are unlikely. The maximum length of an Idempotency-Key is 255 characters.

📘

Idempotency is handled the same way for all resources except for event handling.

Solvimon implements idempotency in two forms. Namely:

1. Reference based Idempotency (only for events)
2. Idempotency-Key based Idempotency (for all other resources)

1. Idempotency based on Reference (events only)

When using the events end-point, idempotency is enforced by the unique resource reference. This is achieved by adding a unique identifier value in the reference field of an event object for a POST request. See an example below:

{
  "reference": "{UNIQUE_IDENTIFIER}"
  "meter_reference": "card_issuing",
  "customer_reference": "Customer_GUID",
    "meter_values": [
    {
      "reference": "card_count",
      "number": "1"
    }
  ],
  "meter_properties": [
    {
      "reference": "card_type",
      "value": "Visa"
    },
    {
      "reference": "card_use_frequency",
      "value": "Single"
    }
  ]
}

If multiple requests with the same reference is sent to the events end-point, a 201 Created response will be returned for each of them. However, only one of those created events will take effect. To get notified that duplicate requests with the same reference as been sent, a Webhook can be configured in Solvimon.

When requests to the events end-point are unsuccessful, the usual status code and response messages will be returned. These unsuccessful requests do not affect idempotency.

📘

Using the unique reference of events for idempotency is only accessible when actively choose to opt-in.

2. Idempotency based on Idempotency-Key

To use idempotency in the Solvimon API that applies to all end-points except events, an Idempotency-Key can be added to the header of an API request. Although not mandatory, Solvimon advises the use of an Idempotency-Key in a POST request.

An idempotent request can be performed by adding Idempotency-Key: UNIQUE ID to the header of a POST request. Idempotent requests are allowed for all Solvimon API users. Idempotency-Keys for different API users will be treated as a unique key.

When the Idempotency-Key was used in a previous request, and the hash of the resubmitted request message is the same as the previous request, the response of the previous request will be returned. To indicate that an idempotent request was returned, the Idempotent-Replayed key in the header is set:

📘

An idempotency key is stored for a maximum of 48 hours after which it expires. A new submission of the same key value will lead to a new request being processed.

Errors & when to retry

When using the same Idempotency-Key, Solvimon guarantees that processing is idempotent. Additionally, depending on the scenario, it might be safe to retry a request with a new idempotency key. If this is possible, the Idempotency-Retryable header will be true.

Summary

A request is retryable if theIdempotency-Retryable header istrue

Not always retryable

• 500 status code. Check if the Idempotency-Retryable header is set and is true. If not, check with Solvimon to continue processing.

Safe to retry, use the same Idempotency-Key:

• 2XX status codes, can be retried and will return the response that's already stored
• 400 status codes, can be retried after correcting the request
• 409 status code, can be retried and will return the same status code
• 422 status code, can be retried and will return the latest status of the processing
• 503 status code, can be retried, the header will be present

Not always retryable: server-side errors (500 status code)

If, by any chance, a server-side error occurs, we might return one of two responses:

1. Idempotency-Retryable=true: this means we have not yet stored the event in our database and the request can safely be retried.
2. Idempotency-Retryable=false (or header/value not available): we have already stored the event in our database and also stored the idempotency cache. This means that retrying it with the same key will result in the same 500 responses. When this happens, retrying will have no effect. In such a case, contact Solvimon. Depending on the cause of the error, we can continue processing and/or determine whether it's safe to resend the same request with a new Idempotency-Key.

Safe to retry: successfully processed request (2xx codes):

When a request has already been processed successfully and is resent with the same Idempotency-Key , we will return the same response as when the request was first processed. Additionally, we will return a Idempotency-Replayed header to indicate that the request has already been processed. This request can be retried and will return the same result each time.

Safe to retry: client-side errors (400 & other 4xx status codes)

A request to our API will be validated before we process it. This validation can fail for multiple reasons, e.g:

• Authorization/authentication fails
• The structure of the JSON is invalid
• A customer cannot be found
• Etc.

For 4xx status codes, it is safe to retry this request with the sameIdempotency-Key

Safe to retry: idempotency errors (409 status code):

When a request is changed but an existing Idempotency-Key is used, the server will return a 409 conflict response. It is safe to retry this and will result in the same 409 conflict response.

Safe to retry: concurrent requests (422 status code)

When a request is retried with the same Idempotency-Key but the previous request has not finished processing yet, we will return a 422 Unprocessable Entity status code. It is safe to retry this request. When the request hasn't finished processing yet we will again return a 422 status code. If it has finished, we will return the result of the processing.

Safe to retry: service unavailable errors (503 status code):

When one of our APIs or other components is temporarily unavailable, a request might get a 503 response. This can always be retried with the sameIdempotency-Key

Additionally, when the idempotency layer itself is unavailable, we will return a 503 status code with a Transient-error header. This request can also be retried with the sameIdempotency-Key