---
title: "Errors and retries"
description: "How the package retries failed requests, which exceptions it throws, and how failover works."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

## What the package retries

The package retries a request only when a second try has a real chance of working. By default it makes 3 attempts in total, counting the first. The same rules apply to chat, embeddings, Clef and Clairic.

| Failure | Retried | Result after the last attempt |
| --- | --- | --- |
| Connect-phase network error (cURL 6, 7, 56, or a connect timeout) | Yes | `ProviderConnectionException` |
| Timeout during transfer (cURL 28 mid-request) | No | `ProviderConnectionException` on `laravel/ai` 0.11 and later. Illuminate `ConnectionException` on 0.9 and 0.10. |
| HTTP 402 | No | `InsufficientCreditsException` |
| HTTP 408 | No | `GatewayTimeoutException` |
| HTTP 429 | Yes, with backoff | `RateLimitedException` |
| HTTP 502, 503, 504 | Yes | `ProviderOverloadedException` |
| HTTP 520, 522, 524 | Yes | `ProviderOverloadedException` |
| HTTP 200 with no text and no tool calls | Not applicable | `EmptyResponseException` |
| HTTP 200 and finish reason `length` | Not applicable | `TruncatedResponseException`, only if `throw_on_truncation` is on |

Between attempts the package waits 500 ms, then 1 s, then 2 s and so on, up to 20 s. If the response has a `Retry-After` header, it waits that long instead, up to 20 s, and it reads both seconds and HTTP-date values.

On `laravel/ai` 1.2.1 and later, Laravel AI has its own retry for a short `Retry-After`. The package turns that one off, so a persistent 429 makes 3 attempts, not 6.

## Retry settings

```php
'workers-ai' => [
    // ...
    'retry'              => true,  // false turns all retrying off
    'retry_attempts'     => 3,     // total attempts, including the first
    'retry_rate_limited' => true,  // false makes a 429 fail at once
],
```

## Why a timeout is not retried

A request that hits your client timeout has already run for the whole timeout, and a retry would run as long. Three attempts would turn a 60-second timeout into about 3 minutes. Raise `#[Timeout]` instead. See [Text generation](/docs/guides/text-generation/).

## HTTP 408

A 408 from the gateway isn't a client timeout. It means the request reached Cloudflare, but the generation ran longer than the gateway is willing to wait. For example, on 2026-09-09 on one account, `@cf/zai-org/glm-5.3-flash` with a 24,000 token cap returned 408 after 709 seconds.

The package throws `GatewayTimeoutException` and doesn't retry, because a retry would take as long. It throws the same exception for a 408 from Clef or Clairic. To fix it, lower the token cap, lower `reasoning_effort`, split the work, or set a failover provider.

## HTTP 429

Laravel AI doesn't retry a 429, but this package does, so when you send many requests at once, one 429 doesn't lose a request.

The package doesn't limit how many requests you send at once, and Cloudflare's limits depend on the account and the model. Limit the fan-out in your own code, for example with a queue rate limiter.

## Failover

Failover means Laravel AI hands a failed call to the next provider in your list. It does that only for exceptions that implement its `FailoverableException` marker. From this package, those are `GatewayTimeoutException`, `RateLimitedException`, `ProviderOverloadedException`, `InsufficientCreditsException` and the connection exceptions.

`EmptyResponseException` and `TruncatedResponseException` don't trigger failover, so catch them in your code. Both extend `Laravel\Ai\Exceptions\AiException`.

```php
use Laravel\Ai\Exceptions\AiException;
use Meirdick\WorkersAi\Exceptions\EmptyResponseException;

try {
    $response = $agent->prompt('...', provider: 'workers-ai');
} catch (EmptyResponseException $e) {
    // Raise the token cap, or lower reasoning_effort, and try again.
} catch (AiException $e) {
    // Any other Laravel AI failure.
}
```

## Other HTTP errors

The package maps only the statuses in the table above. Any other non-2xx status, such as 400, 401, 403, 404, 410 or 413, throws `Illuminate\Http\Client\RequestException`, and these errors don't trigger failover. A bad API token is the usual cause of this error, with a message like `HTTP request returned status code 401: {"code":10000,"message":"Authentication error"}`. Read the status with `$e->response->status()` and the body with `$e->response->json()`.

```php
use Illuminate\Http\Client\RequestException;

try {
    $response = $agent->prompt('...', provider: 'workers-ai');
} catch (RequestException $e) {
    report($e->response->status());
}
```

## Error payloads in a 200 response

Cloudflare sometimes reports an error inside an HTTP 200 response, in one of two shapes: `{"error": {...}}` or `{"errors": [...]}`. When it does, the package throws `AiException` with a message in the form `Workers AI Error: [type] message`.

If a chat response has no `choices`, the package throws `AiException` with `Workers AI Error: Response did not contain any choices.`

## Clef and Clairic errors

Clef and Clairic call `POST /ai/run/{model}`. The package reads the reply whether or not Cloudflare wraps it in `{result, success, errors}`.

| Reply | Result |
| --- | --- |
| HTTP 200 with a non-empty `errors`, or `success: false` | `AiException`, message `Workers AI Error: [type] message` |
| A reply with no `answers` | `AiException`, message `Workers AI Error: Response contained no answers.` |
| HTTP 408 | `GatewayTimeoutException` |

The other statuses follow the table at the top of this page. See [Clef](/docs/system-one/clef/) and [Clairic](/docs/system-one/clairic/).

## Gateway retry

If your AI Gateway also retries, the two layers multiply the attempts. Use one layer: to keep the gateway's retry, set `retry` to `false`.

Source: https://laravel-cf-workersai.meirdick.com/docs/guides/errors-and-retries/index.mdx
