Skip to main content

​
Error handling

Distinguish configuration mistakes (GoPayConfigError) from API responses (GoPayApiError). They need different logging, alerting, and retry behavior.
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). 
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

Never log secrets (clientSecret, bearer tokens), full card numbers, or unnecessary PII. Prefer structured fields such as paymentId, order_number, and correlation IDs.
  • 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.