# Request Frequency

This document applies to the following methods:
- [Update API (v4)](https://developers.google.com/safe-browsing/v4/update-api): [fullHashes.find](https://developers.google.com/safe-browsing/v4/update-api#example-fullHashesfind)
- [Update API (v4)](https://developers.google.com/safe-browsing/v4/update-api): [threatListUpdates.fetch](https://developers.google.com/safe-browsing/v4/update-api#example-threatListUpdatesfetch)

## 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](https://developers.google.com/safe-browsing/v4/update-api#example-fullhashesfind)) or to update the local database ([threatListUpdates.fetch](https://developers.google.com/safe-browsing/v4/update-api#example-threatlistupdatesfetch)).
- 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](https://developers.google.com/safe-browsing/v4/request-frequency#minimum-wait-duration) or [back-off mode](https://developers.google.com/safe-browsing/v4/request-frequency#back-off-mode) time limit has been observed.

## Minimum wait duration

- Both the [fullHashes.find response](https://developers.google.com/safe-browsing/v4/update-api#http-post-response_2) and [threatListUpdates.fetch response](https://developers.google.com/safe-browsing/v4/update-api#http-post-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](https://developers.google.com/safe-browsing/v4/update-api#http-post-response_2) and [threatListUpdates.fetch response](https://developers.google.com/safe-browsing/v4/update-api#http-post-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](https://developers.google.com/safe-browsing/v4/request-frequency#minimum-wait-duration) specified above.