Guides

Set sensible timeouts for high-volume batch jobs

A timeout value that works fine for a single address lookup will cut off a bulk request carrying a few thousand items well before the server has finished processing all of them, which looks like a failure even though the request would have completed given enough time.

Why bulk requests need more time

Each item in a bulk array is a lookup in its own right, so a request with 2,000 items in it involves roughly 2,000 times the processing of a single lookup, even though it is one HTTP call from your side. A one or two second timeout, reasonable for a single address, is nowhere near enough for a request of that size.

Scaling the timeout to the batch

Set your client's timeout proportionally to the size of the array you are sending, with some margin for typical variation, rather than using a single fixed value across every request your code makes, small or large.

timeout_seconds = max(5, item_count * 0.05)

This is a starting point to tune against your own observed behavior, not a fixed number to treat as authoritative, since actual per-item processing time is not a published guarantee.

Preferring smaller chunks over one giant request

Rather than pushing timeout values higher and higher to accommodate an ever larger single request, split a very large job into chunks of a few hundred to a few thousand items each. Smaller chunks need shorter, more predictable timeouts, and a failure partway through only costs you the current chunk rather than the entire job.

Handling a timeout that does happen

If a request does time out on your end, you may not know whether the server actually finished processing it or not. Rather than blindly resubmitting the same chunk, which could double-count against your quota if the original request did complete, check your quota headers from your most recent successful call to estimate whether the timed-out chunk likely went through, and resubmit cautiously.

Cost is unaffected by timeout settings

A timeout is purely a client-side setting about how long you are willing to wait. It has no effect on what a request costs, still one request per item processed, whether your client waited the full duration or gave up early.

Matching your timeout to your batch size, and preferring several smaller chunks over one very large request, keeps large jobs both reliable and easy to resume if something goes wrong. Chunking and quota strategy for large jobs is covered further on the rate limits docs.