Error handling

Catch specific exception types for application decisions, with a fallback for PrismException. Transport failures and invalid application inputs can use other exception types.

Exception types#

The following classes live under Prism\Prism\Exceptions. All extend PrismException except PrismServerException, which extends PHP's Exception directly.

A refusal can also be represented by a response's FinishReason::Refusal; it does not always throw. Inspect finish reasons before treating returned text as a completed result. Streamed deltas are provisional until the stream completes successfully.

Handling failures#

This example records a transport failure without copying potentially sensitive exception messages:

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Support\Facades\Log;
use Prism\Prism\Exceptions\PrismException;
use Prism\Prism\Exceptions\PrismRateLimitedException;
use Prism\Prism\Facades\Prism;

try {
    $response = Prism::text()
        ->using('anthropic', 'claude-sonnet-5-5')
        ->withPrompt('Explain database indexes.')
        ->asText();
} catch (PrismRateLimitedException $error) {
    // Your queue can reschedule using $error->retryAfter or rateLimits.
    throw $error;
} catch (PrismException $error) {
    Log::warning('Provider request failed', [
        'exception_type' => $error::class,
        'http_status' => $error->httpStatus,
    ]);
    throw $error;
} catch (ConnectionException $error) {
    Log::warning('Provider connection failed');
    throw $error;
}

Some audio operations and input validation can throw generic exceptions, InvalidArgumentException or native PHP errors. Keep a suitable application-level Throwable handler; do not assume every possible failure is a PrismException. Tool handlers normally return ToolError rather than throwing; see tool error handling.

Diagnostics and codes#

PrismException::$httpStatus and $responseBody are nullable public fields. Integrations populate them selectively; getCode() is not a reliable cross-provider HTTP-status accessor. Exception messages, chained exceptions and response bodies can contain prompts, partial output, credentials or provider diagnostics. Do not return them directly to a browser or log them indiscriminately.

PrismUrlRefused::code() returns a stable string:

Do not substitute the unguarded fetch after a refusal. See remote media for limits and DNS-boundary details.

PrismRefusalException::code() returns response_refused; refusal() exposes the provider's refusal text explicitly. PrismRunException::code() identifies run_incomplete, run_failed or run_cancelled. Its accessors include status(), runId(), incompleteReason(), incompleteDetails(), output(), citations(), usage() and usageDetails(). These diagnostics can contain partial answers and sensitive content. See Perplexity run failures.

Provider mappings#

Exception mapping varies by integration. The table covers rate-limit, overload and request-size mappings; keep a fallback for generic failures.

✅ mapped to a typed exception · — not mapped

See rate limits for quota buckets and retry guidance, and Batch for local submission limits.