paystack-node-responses-errors

name	paystack-node-responses-errors
description	Use when handling Paystack SDK responses and errors in @alexasomba/paystack-node, including PaystackResponse, unwrap, PaystackError, request IDs, and Paystack API envelopes.
license	MIT
compatibility	Node.js >=22.0.0; ESM-only package; backend/server runtime; imports @alexasomba/paystack-node and @alexasomba/paystack-node/webhooks.

Paystack Node Responses and Errors

Operation helpers return a PaystackResponse<T> wrapper. Handle both HTTP failures and Paystack envelope failures.

Successful responses

Use .unwrap() when you want the typed data payload or an exception on failure.

const result = await paystack.transaction_verify({
  params: { path: { reference: "ref_123" } },
});

const data = result.unwrap();

Use .raw when you need the full Paystack envelope with status, message, data, and meta.

if (result.raw?.status) {
  console.log(result.raw.message);
}

Errors

Catch PaystackError from .unwrap() to access status and request diagnostics.

import { PaystackError } from "@alexasomba/paystack-node";

try {
  const data = result.unwrap();
} catch (error) {
  if (error instanceof PaystackError) {
    console.error(error.status, error.message, error.requestId);
  }
}

PaystackError exposes status, requestId, code, type, and meta. Use isProcessorError() and isValidationError() when branching on Paystack error categories.

Helper exports

Use getPaystackRequestId(headers) when extracting diagnostics from raw responses or mocked transport tests. Request IDs are commonly returned in x-paystack-request-id or x-request-id.

Best practices

• Do not rely only on HTTP status; Paystack may return an envelope with status: false.
• Log requestId when available for support and reconciliation.
• Keep raw response logging redacted; payment metadata can contain personal data.
• Use .response.headers only for transport details such as pagination headers or request IDs.