# Exceptions

A non-2xx PayMongo response, a failed connection, and a webhook with an invalid signature each throw a `PaymongoException` subclass. Catch the base class to handle them all, or a subclass for one kind of failure. They are in `Luigel\Paymongo\Exceptions`.

```text
RuntimeException
└── PaymongoException
    ├── AuthenticationException
    ├── ConnectionException
    ├── InvalidRequestException
    ├── InvalidResponseException
    ├── InvalidWebhookSignatureException
    ├── PaymentDeclinedException
    ├── RateLimitException
    ├── ResourceNotFoundException
    └── ServerException
```

## PaymongoException

`Luigel\Paymongo\Exceptions\PaymongoException` is abstract and extends `RuntimeException`.

Properties:

- `status: ?int`
- `errors: list<ApiError>`

Methods:

- `errors(): array`: The parsed PayMongo `errors[]` entries, when the API returned any.
- `firstError(): ?ApiError`

## AuthenticationException

`Luigel\Paymongo\Exceptions\AuthenticationException` extends [`PaymongoException`](#paymongoexception).

Thrown when PayMongo rejects the API key (HTTP 401).

## ConnectionException

`Luigel\Paymongo\Exceptions\ConnectionException` extends [`PaymongoException`](#paymongoexception).

Thrown when PayMongo cannot be reached at all (DNS failure, timeout, ...).

## InvalidRequestException

`Luigel\Paymongo\Exceptions\InvalidRequestException` extends [`PaymongoException`](#paymongoexception).

Thrown for client errors not covered by a more specific exception (HTTP 400, 403, 422, and any other unmapped 4xx).

## InvalidResponseException

`Luigel\Paymongo\Exceptions\InvalidResponseException` extends [`PaymongoException`](#paymongoexception).

Thrown when PayMongo returns a successful response that cannot be mapped to the expected payload.

## InvalidWebhookSignatureException

`Luigel\Paymongo\Exceptions\InvalidWebhookSignatureException` extends [`PaymongoException`](#paymongoexception).

Thrown when an inbound webhook request fails Paymongo-Signature verification.

## PaymentDeclinedException

`Luigel\Paymongo\Exceptions\PaymentDeclinedException` extends [`PaymongoException`](#paymongoexception).

Thrown when a payment is declined by the processor (HTTP 402).

## RateLimitException

`Luigel\Paymongo\Exceptions\RateLimitException` extends [`PaymongoException`](#paymongoexception).

Thrown when PayMongo rate limits the request (HTTP 429).

Properties:

- `retryAfter: ?int`: Seconds from the `Retry-After` header, when present.

## ResourceNotFoundException

`Luigel\Paymongo\Exceptions\ResourceNotFoundException` extends [`PaymongoException`](#paymongoexception).

Thrown when the requested resource does not exist (HTTP 404).

## ServerException

`Luigel\Paymongo\Exceptions\ServerException` extends [`PaymongoException`](#paymongoexception).

Thrown when PayMongo fails with a server error (HTTP 5xx).