Idempotent Requests

All requests that mutate or create data on our platform support an additional Idempotency-Key header to help in preventing duplicate submissions of requests. Should a network interruption occur, or you otherwise lost a response from a DriveWealth API, you can safely perform the request provided that you send the same value as the Idempotency-Key.

The key you provide can be any value, though we suggest randomly-generated UUIDs to prevent collisions. Keys must be at least 16 characters in length.

Idempotency keys are saved for 4 days. Within this time period, sending any request with a duplicate key will return the exact same response as the original request, including the same status code and payload.

POST /back-office/orders HTTP/1.1
Host: bo-api.drivewealth.io
dw-client-app-key: :appKey
Accept: application/json
dw-auth-token: :authKey
Idempotency-Key: 418a5506-256c-4c3c-9d4d-f491522cf7f2
dw-request-timestamp: 2019-06-25T23:40:12.345Z

{
  "accountNo": "DWPH000003",
  "orderType": "MARKET",
  "symbol": "AMZN",
  "side": "BUY",
  "amountCash": 100,
}

Retrying requests

Idempotency allows you to create a network layer that automatically retries all DriveWealth requests when you fail to receive a response. Please keep in mind that requests should never be unconditionally retried, as failing to receive a response does not necessarily mean that DriveWealth is not receiving and responding.

Your network layer should have a maximum number of retries before it gives up and follows other failover procedures. More importantly, retrying multiple times immediately may be futile—if there is a network issue or connectivity issue, it may not be resolved within the maximum number of retries if these requests are issued in quick sucession. We recommend an exponential backoff or similar pattern of requests, such as:

  1. T: Issue request
  2. T+1s: Retry 1
  3. T+3s: Retry 2
  4. T+10s: Retry 3
  5. T+30s: Retry 4

Extended idempotency

While idempotency keys will only be stored for 4 days, you may avail yourself of the dw-request-timestamp header to help avoid other technical failures that would resubmit old requests. For example, if you have a message-queue-based system for issuing requests to DriveWealth and are concerned about the possibility of repeating old requests, store the original timestamp in each message as this header. When DriveWealth sees this timestamp, it will reject the request if it is older than the 4-day idempotency limit.

Note that when requests are rejected for this reason, the original response contents will no longer have been preserved, and will not be sent back to you.