> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bundleup.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Retries

BundleUp’s proxy can automatically retry **safe** requests when an upstream API fails or rate-limits you. This improves reliability without requiring you to implement retry logic in your client.

## **When retries happen**

BundleUp retries a request only when all of the following conditions are met.

The HTTP method must be idempotent. Only `GET`, `HEAD`, and `OPTIONS` requests are retried by default. Write methods such as `POST`, `PUT`, `PATCH`, and `DELETE` are never retried automatically.

The upstream response must be retryable. BundleUp retries on **408 Request Timeout**, **429 Too Many Requests**, **502 Bad Gateway**, **503 Service Unavailable**, and **504 Gateway Timeout**. Other status codes — including `500` and `501` — are returned immediately without a retry. Requests that time out at the proxy (20 seconds for the first attempt, 10 seconds for each retry) are treated as `408` and are also retried.

The request must not have exceeded the retry limit. By default, BundleUp performs **up to 4 total attempts**, which includes the initial request and up to **3 retries**.

## **Custom retry count**

You can override the default retry behavior by providing a custom retry count in the request headers.

```
BU-Max-Retries: <number>
```

The value represents the **maximum number of retries**, not total attempts.

For example:

```
BU-Max-Retries: 4
```

This results in up to **5 total attempts** (1 initial request + 4 retries).

The maximum allowed value is **5**. Any value greater than 5 is capped at 5. If the header is omitted, BundleUp uses the default retry limit.

This header applies per request and does not affect other requests on the same connection.

## **Retry-After support**

If the upstream response includes a Retry-After header, BundleUp honors it.

```
Retry-After: 3
```

In this case, BundleUp waits **3 seconds** before retrying instead of using its default exponential backoff. `Retry-After` values are capped at **15 seconds** to avoid long delays, and both the numeric (seconds) and HTTP-date forms are supported. When no `Retry-After` header is present, BundleUp falls back to exponential backoff with jitter.

## **Important notes**

Retries are only applied to requests that are safe to repeat. BundleUp will never retry non-idempotent requests, even if `BU-Max-Retries` is provided.

If all retry attempts fail, the final upstream response is returned to the client.