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
'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.
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.
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().
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 and 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.