This document applies to the following methods:
Update requests
To prevent server overload and to benefit from optimal protection, the Update API (v4) imposes time intervals for how often a client can send requests to the Safe Browsing server to perform URL checks (fullHashes.find) or to update the local database (threatListUpdates.fetch).
The initial request for data must happen at a random interval between 0 and 1 minutes after the client starts or wakes up. Subsequent requests can happen only after the minimum wait duration or back-off mode time limit has been observed.
Minimum wait duration
Both the
fullHashes.find response and
threatListUpdates.fetch response
have a minimumWaitDuration field that clients must obey.
If the minimumWaitDuration field is not set in the response, clients can
update as frequently as they want and send as many threatListUpdates or fullHashes requests as
they want.
If the minimumWaitDuration field is set in the response, clients cannot
update more frequently than the length of the wait duration. For example, if a fullHashes response
contains a minimum wait duration of 1 hour, the client must not send send any fullHashes requests
until that hour passes, even if the user is visiting a URL whose hash prefix matches the local
database. (Note that clients can update less frequently than the minimum wait duration but this
may negatively affect protection.)
Back-off mode
Automatic back-off applies to both the fullHashes.find response and threatListUpdates.fetch response.
Clients that receive an unsuccessful HTTP response (that is, any HTTP status code other than
200 OK) must enter back-off mode. Once in back-off mode, clients must wait the computed time
duration before they can issue another request to the server.
Clients must use the following formula to compute the back-off time duration:
MIN((2N-1 * 15 minutes) * (RAND + 1), 24 hours)N corresponds to the number of consecutive, unsuccessful requests that the client experiences (starting with N=1 after the first unsuccessful request). RAND is a random number between 0 and 1 that needs to be picked after every unsuccessful update.
Once a client receives a successful HTTP response, the client must exit back-off mode and follow the minimum wait duration specified above.