Skip to main content

​
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"
}

​
Errors

StatusMeaningTypical fixRetry?
400Validation / business rule violationFix the request body/paramsNo
401Missing/invalid credentialsCheck headers and token formatNo
403Authenticated but forbiddenVerify permissions/scopeNo
404Not foundVerify IDs and environmentNo
429Rate limitedBackoff; respect Retry-AfterYes (after delay)
5xxTransient server errorRetry with backoff if safeOften

​
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 API keys