---
name: paystack-browser-responses-errors
description: Use when handling Paystack SDK responses and errors in @alexasomba/paystack-browser, including PaystackResponse, unwrap, PaystackError, request IDs, and Paystack API envelopes.
license: MIT
compatibility: "Modern browsers and bundlers; package tooling/SSR builds require Node.js >=22.0.0; ESM package; public-key frontend runtime only."
---

# Paystack Browser Responses and Errors

Browser SDK operations return `PaystackResponse<T>`. Use `.unwrap()` for typed data or an exception.

```ts
const result = await paystack.transaction_initialize({
  body: { email: "customer@example.com", amount: 5000 },
});

const data = result.unwrap();
```

## Error handling

```ts
import { PaystackError } from "@alexasomba/paystack-browser";

try {
  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()` for programmatic branching, but do not show raw diagnostic details directly to users.

## Helper exports

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

## Best practices

- Show user-safe messages in the UI; keep diagnostic details in logs.
- Do not expose secret keys, raw headers, or sensitive metadata in browser logs.
- Treat Paystack envelope `status: false` as failure even with HTTP 2xx.
- Use `response.headers` only for transport details such as pagination headers.