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

# Automatic Retries

> Automatically retry failed LLM requests with exponential backoff.

* Up to **5 retry attempts**
* Trigger on **specific error codes**
* **Exponential backoff** to prevent overload
* Optionally respect provider's `Retry-After` headers

## Examples

```json Basic (5 attempts) theme={"system"}
{
  "retry": { "attempts": 5 },
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

```json Specific Error Codes theme={"system"}
{
  "retry": { "attempts": 3, "on_status_codes": [429, 503] },
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

```json Respect Retry-After Headers theme={"system"}
{
  "retry": { "attempts": 3, "on_status_codes": [429], "use_retry_after_headers": true },
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

> [!NOTE]
>
> The `@provider-slug/model-name` format automatically routes to the correct provider. Set up providers in [Model Catalog](https://stratacloudmanager.paloaltonetworks.com/).

## Retry on Specific Error Codes

Default retry codes: **\[429, 500, 502, 503, 504, 529]**

Override with `on_status_codes`:

```json theme={"system"}
{
  "retry": { "attempts": 3, "on_status_codes": [408, 429, 500] },
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

> [!NOTE]
>
> When `on_status_codes` is set, retries trigger **only** on those codes—not the defaults.

## Respect Provider Retry Headers

Enable `use_retry_after_headers` to use the provider's `retry-after-ms`, `x-ms-retry-after-ms`, or `retry-after` headers instead of exponential backoff.

```json theme={"system"}
{
  "retry": { "attempts": 3, "on_status_codes": [429], "use_retry_after_headers": true },
  "override_params": { "model": "@openai-prod/gpt-4o" }
}
```

> [!NOTE]
>
> When `use_retry_after_headers` is set to true and the provider includes Retry-After or Retry-After-ms headers in their response, the AI Gateway will use these values to determine the wait time before the next retry attempt, overriding the exponential backoff strategy.
> If the provider doesn't include these headers in the response, the AI Gateway will fall back to the standard exponential backoff strategy.
> The cumulative retry wait time for a single request is capped at 60 seconds. For example, if the first retry has a wait time of 20 seconds, and the second retry response includes a Retry-After value of 50 seconds, the request will fail since the total wait time (20+50=70) exceeds the 60-second cap. Similarly, if any single Retry-After value exceeds 60 seconds, the request will fail immediately.

## Exponential Backoff

| Attempt | Wait Time |
| - | - |
| Initial | Immediate |
| 1st retry | 1 second |
| 2nd retry | 2 seconds |
| 3rd retry | 4 seconds |
| 4th retry | 8 seconds |
| 5th retry | 16 seconds |

## Retry Attempt Header

Check `x-portkey-retry-attempt-count` in responses:

| Value | Meaning |
| - | - |
| `-1` | All retries exhausted, request failed |
| `0` | No retries configured |
| `>0` | Successful on this retry attempt |

> [!NOTE]
>
> Retry attempts aren't logged individually. Response times are summed in a single log entry.


## Related topics

- [Vercel AI SDK](https://docs.portkey.ai/docs/aigw/integrations/libraries/vercel.md)
- [DSPy](https://docs.portkey.ai/docs/aigw/integrations/libraries/dspy.md)
- [Tracing](https://docs.portkey.ai/docs/aigw/product/observability/traces.md)
- [Anthropic Computer Use](https://docs.portkey.ai/docs/aigw/integrations/libraries/anthropic-computer-use.md)
- [OpenAI Agent Builder (TypeScript)](https://docs.portkey.ai/docs/aigw/integrations/libraries/openai-agent-builder.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.