Skip to main content
Providers fail occasionally: a timeout, a 503 during a deploy, a 429 when you’ve hit their limit. For requests that are safe to repeat, BundleUp retries automatically so a brief blip doesn’t reach your code. Retries apply to the Proxy and the Unified API. MCP requests are never retried; your MCP client decides what to do.

​
When a request is retried

A request is retried only when all of these are true:
  1. The method is idempotent: GET, HEAD or OPTIONS. POST, PUT, PATCH and DELETE are never retried, because repeating them could create or change something twice.
  2. The failure is transient: 408 Request Timeout, 429 Too Many Requests, 502 Bad Gateway, 503 Service Unavailable or 504 Gateway Timeout. A provider that doesn’t answer within the timeout counts as 408; a provider BundleUp can’t reach at all counts as 502.
  3. There are retries left. By default, 3 retries: up to 4 attempts in total.
Any other response (including 400, 401, 403, 404 and 500) is returned straight away.

​
How long BundleUp waits

  • If the provider sent a Retry-After header (seconds or an HTTP date), BundleUp waits that long, capped at 15 seconds.
  • Otherwise it backs off exponentially: about 250 ms, 500 ms, 1 s, 2 s, 4 s for attempts 1 to 5, each with ±20% random jitter so many clients don’t retry in lockstep.
If every attempt fails, you get the last response from the provider.

​
Changing the retry count

Send BU-Max-Retries to set the maximum number of retries (not attempts) for one request:
The header only affects that request. It doesn’t make non-idempotent methods retryable. Turn retries off (0) when you have your own retry logic, or when a fast failure is more useful than a late success, such as in a user-facing request with a tight deadline. Turn retries up for background jobs against providers known to be flaky.

​
Retries and usage

Each retry is a real call to the provider and is logged and counted as a request. A GET that succeeds on the third attempt counts as three requests. Retries also count toward the connection’s rate limit at the provider, though not toward BundleUp’s.

​
Retrying writes yourself

Because writes are never retried automatically, handle their failures in your code. If the provider supports idempotency keys (for example, an Idempotency-Key header), send one. The Proxy forwards it unchanged, so you can retry the write safely.