Error handling

Unlike SDKs that return an { data, error } tuple, @pulsebyshiga/node returns the value directly and throws. Catch these:

Error	When	Useful fields
`PulseApiError`	The engine responded with a non-2xx.	`status`, `code`, `message`, `requestId`
`PulseConnectionError`	Network failure / timeout, after the built-in retries.	`message`
`PulseAccessError`	SDK misuse (e.g. an API key constructed in a browser).	`message`
`SignatureVerificationError`	`webhooks.verify()` — bad signature, replay, or malformed.	`message`

All extend PulseError, so catch (e) { if (e instanceof PulseError) … } catches everything from the SDK:

try {
  const session = await pulse.collectionSessions.create(payload);
  return session;
} catch (error) {
  if (error instanceof PulseApiError) {
    logger.error('Pulse rejected the session', {
      status: error.status,
      code: error.code,
      requestId: error.requestId,
    });
  } else if (error instanceof PulseConnectionError) {
    logger.error('Could not reach Pulse', { message: error.message });
  }
  throw error; // re-throw, or map into your own error layer — see below
}

Optional: map into your app’s error layer

If your backend centralizes errors (e.g. behind your own ErrorFactory), map the SDK’s typed errors the same way you wrap any vendor — keeping the raw vendor detail in metadata and logs, never in the customer-facing message. ErrorFactory and logger below are your own utilities, not part of the SDK — the SDK’s only contract is the four typed errors above.

} catch (error) {
  logger.error('Pulse collectionSessions.create failed');

  if (error instanceof PulseApiError) {
    throw ErrorFactory.externalApi.error('Pulse', error.status, {
      endpoint: 'collectionSessions.create',
      externalApiResponse: {
        code: error.code,
        message: error.message,
        requestId: error.requestId,
      },
    });
  }

  throw ErrorFactory.fromError(error, 'EXTERNAL_API_ERROR', {
    externalApiName: 'Pulse',
    endpoint: 'collectionSessions.create',
  });
}

Error codes

PulseApiError.code is a string set by the API — it isn’t a frozen enum yet. The values below are the ones you’ll encounter in today’s sandbox; branch on the codes you handle and treat any unrecognised code defensively (fall back on error.status and error.message).

`code`	HTTP	Meaning
`unauthorized`	401	Missing or invalid API key / session token
`session_not_found`	401	The `cs_` session token is unknown or expired
`order_not_found`	404	No order with that id
`not_found`	404	Resource not found
`invalid_request`	400	Malformed request body
`invalid_amount`	400	Amount missing or not greater than zero
`invalid_quote`	400	Quote is missing, mismatched, or has expired
`invalid_gate`	400	Unknown or unsupported gate
`missing_user_ref`	400	Naira gate requires a `user_ref`
`invalid_account_block`	400	Naira `account` block is missing or malformed
`invalid_selection`	400	Selected asset/network isn’t offered on this order
`not_selectable`	409	Order is past the selection stage
`resolve_failed`	400	Bank-account resolution failed
`network_not_enabled`	400	Network disabled for this partner (dashboard config)
`asset_not_enabled`	400	Asset disabled for this partner
`no_deposit`	409	Action needs a deposit that hasn’t arrived
`invalid_event`	400	Unknown sandbox simulate event
`internal`	500	Unexpected server error (retried automatically)
`unknown_error`	—	SDK fallback when the response carries no `code`

Get started

Concepts

Backend integration

Render the payment moment

Testing & go-live

Optional: map into your app’s error layer

Error codes

​Optional: map into your app’s error layer

​Error codes

Optional: map into your app’s error layer

Error codes