Errors

Overview

Pepay returns JSON error responses. For debugging, always log:

HTTP status code
an error code / error_code when present
an error message (message or error.message)
request id headers when present (x-request-id, request-id)

If you’re using the SDK, errors are normalized into typed exceptions and include safe retry behavior for retryable cases.

Authentication

Some errors happen before authentication succeeds (for example, missing/invalid headers). Others are authorization errors (403) after the request is authenticated but lacks permissions or scope.

Request

When reporting an issue, include:

the endpoint + method
the request id header (if present)
a sanitized excerpt of the response body (do not include API keys or session tokens)

Example request (invalid API key):

BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/v1/invoices?limit=1" \
  -H "x-api-key: sk_live_invalid"

Response

Error envelopes may vary slightly by endpoint. Common shapes include: success=false envelope:

{
  "success": false,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid API key"
  }
}

Legacy {error, code} envelope:

{
  "error": "Failed to fetch wallets",
  "code": "INTERNAL_SERVER_ERROR"
}

Status	Meaning	Typical fix	Retry?
`400`	Validation / business rule violation	Fix the request body/params	No
`401`	Missing/invalid credentials	Check headers and token format	No
`403`	Authenticated but forbidden	Verify permissions/scope	No
`404`	Not found	Verify IDs and environment	No
`429`	Rate limited	Backoff; respect `Retry-After`	Yes (after delay)
`5xx`	Transient server error	Retry with backoff if safe	Often

Examples

Example (SDK error handling):

import { Pepay } from 'pepay';

const pepay = new Pepay({ apiKey: process.env.PEPAY_API_KEY! });

try {
  await pepay.merchants.invoices.list({ limit: 1 });
} catch (err) {
  // Log status + code/message, but never log secrets.
  console.error(err);
}

Next: Merchant APIs

Overview

API

Merchant

Tokens

Commerce

Payor

WebSockets

Webhooks

Errors

Overview

Authentication

Request

Response

Errors

Examples

​Overview

​Authentication

​Request

​Response

​Errors

​Examples

Overview

Authentication

Request

Response

Errors

Examples