Request Frequency
Stay organized with collections
Save and categorize content based on your preferences.
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-09-18 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-09-18 UTC."],[[["\u003cp\u003eThe Google Safe Browsing Update API (v4) enforces request frequency limits to prevent server overload and maintain optimal protection.\u003c/p\u003e\n"],["\u003cp\u003eClients should adhere to the \u003ccode\u003eminimumWaitDuration\u003c/code\u003e field provided in API responses to determine update frequency.\u003c/p\u003e\n"],["\u003cp\u003eIf the \u003ccode\u003eminimumWaitDuration\u003c/code\u003e field is not set, clients can update as frequently as needed; if set, updates should not exceed the specified duration.\u003c/p\u003e\n"],["\u003cp\u003eUpon receiving unsuccessful HTTP responses, clients must enter back-off mode, delaying subsequent requests using a calculated time duration formula.\u003c/p\u003e\n"],["\u003cp\u003eAfter a successful response, clients exit back-off mode and resume following the \u003ccode\u003eminimumWaitDuration\u003c/code\u003e guidelines for updates.\u003c/p\u003e\n"]]],["The Update API v4's `fullHashes.find` and `threatListUpdates.fetch` methods require clients to adhere to request time intervals. Initial requests must be sent within 0-1 minutes of startup, and subsequent requests must observe the `minimumWaitDuration` or `back-off mode`. If `minimumWaitDuration` isn't set, clients can update freely; if set, they must wait for the specified duration. Unsuccessful HTTP responses trigger back-off mode, using a formula to determine the wait time, until a successful response occurs.\n"],null,["# Request Frequency\n\nThis document applies to the following methods:\n- [Update API (v4)](/safe-browsing/v4/update-api): [fullHashes.find](/safe-browsing/v4/update-api#example-fullHashesfind)\n- [Update API (v4)](/safe-browsing/v4/update-api): [threatListUpdates.fetch](/safe-browsing/v4/update-api#example-threatListUpdatesfetch)\n\nUpdate requests\n---------------\n\n- 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](/safe-browsing/v4/update-api#example-fullhashesfind)) or to update the local database ([threatListUpdates.fetch](/safe-browsing/v4/update-api#example-threatlistupdatesfetch)).\n- 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](/safe-browsing/v4/request-frequency#minimum-wait-duration) or [back-off mode](/safe-browsing/v4/request-frequency#back-off-mode) time limit has been observed.\n\nMinimum wait duration\n---------------------\n\n- Both the [fullHashes.find response](/safe-browsing/v4/update-api#http-post-response_2) and [threatListUpdates.fetch response](/safe-browsing/v4/update-api#http-post-response) have a `minimumWaitDuration` field that clients must obey.\n- 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.\n- 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.)\n\nBack-off mode\n-------------\n\n- Automatic back-off applies to both the [fullHashes.find response](/safe-browsing/v4/update-api#http-post-response_2) and [threatListUpdates.fetch response](/safe-browsing/v4/update-api#http-post-response).\n- 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.\n- Clients must use the following formula to compute the back-off time duration: \n\n```scdoc\nMIN((2N-1 * 15 minutes) * (RAND + 1), 24 hours)\n```\n- 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.\n- Once a client receives a successful HTTP response, the client must exit back-off mode and follow the [minimum wait duration](/safe-browsing/v4/request-frequency#minimum-wait-duration) specified above."]]
