Skip to content

Errors and retries

How the package retries failed requests, which exceptions it throws, and how failover works.

Updated

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.

Type to search…

↑↓ navigate↵ selectEsc close