Timeouts, Retries & Rate Limits
Timeouts
The average response time to a request to the Connect Direct REST API can be expressed in hundreds of milliseconds. Depending on the time of day, the request type*, and other factors a response may take less than one hundred milliseconds or may take one, two, or three hundred milliseconds. Averages mask extremes but it’s rare for responses to take more than a few seconds. That said, in extreme conditions, a response may take 30 seconds or more. The longer a request takes the more likely an error will be returned. “Error” in this context means both
A non “200” http response status and
A “200” http response status with a non-zero “responseCode” value in the payload
For info, server-side time-outs will return either a “500” or a “502” http response status.
Considering the above, Savvy recommends that integrators implement request time-outs with a wait time of 90 seconds rather than wait “forever”. While integrators may retry a request in response to any failure, Savvy recommends that request time-outs are always followed by at least one retry. This is because “something” (either an error or success) should have happened in such a time.
Retries
“Retry” means using the exact same values for all payload fields including RequestId. It should be noted that while Savvy does not prohibit it, there is no point in issuing a retry to an error denoted “200” http response status with a non-zero “responseCode” value in the payload - the same response will always be returned.
Most endpoints provide an “isFirstResponse” field in the response payload. If, in response to a retry, this is “False” it means that the earlier request ran to completion and that the values being returned are those generated by that run - i.e., retries never result in duplication. The “isFirstResponse” field is purely for information.
At this time, Savvy does not mandate that integrators should implement a retry backoff strategy. Neither does it implement a retry backoff internally. However, we may do one or both in the future. While sufficient warning will be given before any such change is implemented it is advised that integrators prepare for these possibilities by
Making provision for the implementation of the exponential backoff algorithm described here [1].
Making provision for using different (larger) request time-out values for retries
Rate Limits
To protect against malicious use, the Connect Direct REST API implements call rate limiting. If a caller hits a limit, the http response status will be 429 (Too Many Requests). The response payload in this case contains “statuscode” and “message” (example below). The message will contain the number of seconds that should elapse before a retry. This should be respected. Because the request will not have reached the core infrastructure, the caller can be sure it was not successful.
{"statusCode": 429,"message": "Rate limit is exceeded. Try again in 19 seconds."}
Because the purpose of call rate limiting is to prevent malicious use, not block legitimate transactions you should contact Savvy support when a 429 response is received.