Maximum wait duration, Retries & Rate Limits
Maximum wait duration
Typical response times for the Connect Direct REST API are under 100 milliseconds. Depending on factors such as time of day and request type, responses may range from under 100 milliseconds to 100–300 milliseconds. While averages hide outliers, it’s uncommon for a response to take more than a few seconds. However, under extreme conditions, a response may take 10 seconds or longer. As response times increase, the likelihood of receiving an error also increases.
In this context, an “error” refers to either:
An HTTP status code other than 200, or
A 200 HTTP status with a non-zero responseCode value in the payload.
Server-side timeouts typically return HTTP status 500 or 502.
Given this behavior, Savvy recommends that integrators use a maximum request wait duration of 10 seconds rather than waiting indefinitely. If a request fails—including due to wait duration being exceeded —integrators may retry the request. Savvy advises performing up to two retries after any fail, since within that time some form of response (success or error) should normally occur.
Retries
A retry is a request sent with exactly the same payload values, including the original RequestId. Although Savvy allows retries, issuing one after receiving an HTTP 200 response that contains a non-zero responseCode is unnecessary—the same response will always be returned.
Most endpoints include an isFirstResponse field in the response payload. When a retry returns isFirstResponse = False, it indicates that the original request already completed successfully, and the system is returning that original result. In other words, retries will never cause duplicate processing; the isFirstResponse flag is informational only.
Currently, Savvy does not require integrators to implement retry backoff logic, nor does it apply backoff internally. However, this may change in the future. If changes are introduced, sufficient notice will be provided. Integrators are therefore encouraged to prepare by:
Designing for the potential implementation of the exponential backoff algorithm described in reference [1].
Allowing for the possibility of using larger request timeout values when issuing 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.