> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zabcik.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Handle GoPay API and SDK configuration failures predictably in TypeScript.

# Error handling

<Info>
  Distinguish **configuration mistakes** (`GoPayConfigError`) from **API responses** (`GoPayApiError`). They need different logging, alerting, and retry behavior.
</Info>

The SDK throws dedicated error classes for API and configuration failures.

## Error classes

### `GoPayApiError`

Thrown for non-2xx HTTP responses from GoPay endpoints.

Useful fields:

* `status`: HTTP status code
* `endpoint`: full endpoint URL or endpoint path
* `errors`: parsed GoPay field errors when present
* `rawResponse`: parsed JSON payload or raw text payload

### `GoPayConfigError`

Thrown when client configuration is invalid (for example invalid `gatewayUrl` or missing credentials).

## Recommended pattern

```ts theme={null}
import { GoPayApiError, GoPayConfigError } from 'gopay-sdk';

try {
  // SDK call...
} catch (error) {
  if (error instanceof GoPayConfigError) {
    // fail fast; fix deployment config
    throw error;
  }

  if (error instanceof GoPayApiError) {
    if (error.status >= 500) {
      // retryable in many setups
      console.error('Transient GoPay error', error.endpoint, error.rawResponse);
    } else {
      // usually validation/business issue
      console.error('Request rejected', error.status, error.errors);
    }
    throw error;
  }

  throw error;
}
```

## Suggested retry policy

* Retry only safe/idempotent operations by default (for example `getPayment`)
* Use bounded retries with exponential backoff
* Add jitter to avoid synchronized retries
* Do not blindly retry validation failures (`4xx` with clear field errors)

## Logging best practices

<Warning>
  Never log secrets (`clientSecret`, bearer tokens), full card numbers, or unnecessary PII. Prefer structured fields such as `paymentId`, `order_number`, and correlation IDs.
</Warning>

* Log `endpoint`, `status`, and sanitized error metadata (not raw bodies with PII).
* Include a correlation or request ID on every log line for support and tracing.