Errors and retries.

Every package error extends PayrexException. Catch the base class for a single application-level failure path or a subclass when the response needs special handling:

use ByRcsc\LaravelPayrex\Exceptions\InvalidRequestException;
use ByRcsc\LaravelPayrex\Exceptions\PayrexException;

try {
    $intent = Payrex::paymentIntents()->create(
        amount: 2_000,
        paymentMethods: ['card'],
    );
} catch (InvalidRequestException $exception) {
    $detail = $exception->firstError()?->detail;
    $amountErrors = $exception->errorsFor('amount');
} catch (PayrexException $exception) {
    report($exception);
}

Exception reference

An invalid payment-intent amount outside the package's documented local range throws PHP's InvalidArgumentException before any network request.

Inspecting API errors

API exceptions expose the HTTP status, decoded response, and typed errors:

try {
    Payrex::paymentIntents()->retrieve('pi_...');
} catch (PayrexException $exception) {
    $exception->statusCode;
    $exception->response;
    $exception->errors();
    $exception->firstError();
    $exception->errorsFor('amount');
    $exception->hasErrorCode('parameter_invalid');
}

Each PayrexError has code, detail, parameter, meta, and raw properties. Its type() helper reads a type value from meta when available.

Response headers after a failure

lastResponse() is updated before an API exception is thrown, so response headers remain available:

use ByRcsc\LaravelPayrex\Exceptions\RateLimitException;

try {
    Payrex::customers()->list();
} catch (RateLimitException $exception) {
    $response = Payrex::lastResponse();

    logger()->warning('PayRex rate limit reached', [
        'status' => $response?->status,
        'headers' => $response?->headers,
    ]);
}

PayRex does not guarantee particular response-header names. Read headers defensively and allow for null.

Retry behavior

Only GET requests can retry automatically. A configured attempt count above one retries after:

• a connection exception;
• HTTP 429; or
• HTTP 5xx.

Configure attempts and the delay:

PAYREX_RETRY_TIMES=3
PAYREX_RETRY_SLEEP=250

Set attempts to 1 to disable retries.

POST, PUT, and DELETE requests are never retried automatically. PayRex does not document idempotency keys, so replaying a mutation after an ambiguous timeout could duplicate a payment, refund, or other resource.

Handling ambiguous mutations

When a mutation times out, do not blindly repeat it. Record the local operation and reconcile it using a safe retrieval endpoint, a webhook, the PayRex dashboard, or PayRex support. Design local state transitions so a later verified webhook can finish the operation without duplicating it.

What to read next

• Security and operations to design production recovery and monitoring.
• Receiving webhooks to reconcile mutations from signed events.
• Troubleshooting to diagnose specific exception messages.