Request Frequency

  • The Google Safe Browsing Update API (v4) enforces request frequency limits to prevent server overload and maintain optimal protection.

  • Clients should adhere to the minimumWaitDuration field provided in API responses to determine update frequency.

  • If the minimumWaitDuration field is not set, clients can update as frequently as needed; if set, updates should not exceed the specified duration.

  • Upon receiving unsuccessful HTTP responses, clients must enter back-off mode, delaying subsequent requests using a calculated time duration formula.

  • After a successful response, clients exit back-off mode and resume following the minimumWaitDuration guidelines for updates.

This document applies to the following methods:

  • Update API (v4): fullHashes.find
  • Update API (v4): threatListUpdates.fetch

    • 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.