Errors

All errors return a single nested envelope. The flat {error, code} shape used in earlier docs has been replaced. See the migration note below if you have older code.

{
  "error": {
    "message": "Invalid API key. Verify the key in your dashboard at https://dashboard.paybridgenp.com.",
    "type": "authentication_error",
    "code": "api_key_invalid",
    "request_id": "req_2Je91NlWKuXkdXUJOK9gaHNW"
  }
}

Fields

Field	Type	Description
`error.message`	string	Human-readable explanation. Safe to surface in logs; safe to show developers. Not always safe to show end users.
`error.type`	string (enum)	Broad category - SDKs use this to instantiate typed exceptions. See error types.
`error.code`	string	Specific, stable identifier for programmatic branching. See error codes.
`error.request_id`	string	Same value as the `X-Request-Id` response header. Quote in support requests for fastest triage.
`error.suspension`	object	Present only on `code: "account_suspended"` - includes `suspended_at` and `reason`.
`error.pause`	object	Present only on `code: "token_paused"` - includes `paused_at` and `reason`.

Error types

Use error.type to route an error to the right handler. Each type maps to a typed exception class in the SDKs.

Type	Status range	Meaning
`authentication_error`	401	Auth credentials missing or invalid
`account_error`	403, 410, 423	Credentials valid but the account or token is not in good standing
`permission_error`	402, 403	Action not permitted (missing scope, wrong key type, plan gate, or a quota/entitlement wall)
`invalid_request_error`	400, 404, 409, 422	Request was malformed, references something that does not exist, or violates business rules
`idempotency_error`	409	Concurrent request with same `Idempotency-Key`
`rate_limit_error`	429	Rate-limit window exhausted - back off and retry
`api_error`	500-599	Server-side failure - safe to retry

HTTP status codes

Status	Typical type	Notes
`400`	`invalid_request_error`	Validation failure
`401`	`authentication_error`	Missing or invalid API key
`402`	`permission_error`	Plan quota or entitlement wall - volume cap, key/endpoint cap, or MCP write entitlement
`403`	`permission_error` or `account_error`	Permission gate or suspended account
`404`	`invalid_request_error`	Resource not found or not visible to your project
`409`	`invalid_request_error` or `idempotency_error`	State conflict, or Idempotency-Key collision
`410`	`account_error`	Merchant can no longer accept payments
`422`	`invalid_request_error`	Request is valid but the action cannot be performed
`423`	`account_error`	MCP token paused for anomalous activity
`429`	`rate_limit_error`	See `Retry-After`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers
`500`	`api_error`	Server-side failure - safe to retry with backoff
`503`	`api_error`	Temporary maintenance - retry shortly

Error codes

Authentication

Code	Status	Description
`api_key_missing`	401	No `Authorization` header, or empty key portion
`api_key_invalid`	401	Key not recognized - typo, deleted project, or wrong environment
`api_key_revoked`	401	Key was explicitly revoked from the dashboard
`api_key_expired`	401	Key passed its expiration timestamp
`api_key_must_be_secret`	403	Endpoint requires `sk_...`; a publishable `pk_...` was sent
`account_suspended`	403	Merchant account suspended - see `error.suspension`
`token_paused`	423	MCP token paused due to anomalous activity - see `error.pause`
`forbidden`	403	Key doesn’t have permission for this action, or the feature requires a higher plan - see `requiredPlan`

Resources

Code	Status	Description
`not_found`	404	Resource not found or not visible to your project
`invalid_state`	409	Resource is in a state that doesn’t allow this action
`idempotency_conflict`	409	Concurrent request with same `Idempotency-Key` is still in flight

Billing

Code	Status	Description
`trial_not_active`	409	The subscription’s trial is not active (already ended or never started) and cannot be modified

Other billing rule violations return a descriptive error.message with error.type set to invalid_request_error and the HTTP status shown, without a dedicated error.code today. This covers a missing plan, coupon, promotion code, or customer (404), an inactive coupon or expired promotion code, and a subscription that is not in an active state (409 or 422). Branch on error.type and the HTTP status, and read error.message. Dedicated billing codes are being added incrementally.

Plans, quotas, and availability

These are the gates paying merchants hit as they grow. Each carries extra fields for programmatic handling.

Code	Status	Description
`forbidden`	403	A feature requires a higher plan - `requiredPlan`, `currentPlan`, and `entitlement` accompany the error
`quota_exceeded`	402	A plan limit was reached - live monthly volume cap, or an API-key / webhook-endpoint cap. Carries `requiredPlan`, `limit`, and `current`
`entitlement_required`	402	An MCP token’s write scopes aren’t available on the merchant’s current plan - carries `entitlement`
`insufficient_scope`	403	The API key is missing a required scope - the needed scope is in the `WWW-Authenticate` header
`over_spend_cap`	403	An MCP token exceeded its 24h spend cap - carries `spent_paisa`, `cap_paisa`, `remaining_paisa`, and `reset_at`
`merchant_suspended`	410	The merchant can no longer accept payments (hosted checkout / payment-link surfaces)
`maintenance_mode`	503	PayBridgeNP is briefly in maintenance - retry shortly

Validation + rate limiting

Code	Status	Description
`invalid_request_error`	400	Generic validation failure - read `error.message` for the specific issue
`rate_limited`	429	Public-API rate-limit window exhausted

The `account_suspended` error

When your account is suspended, every API request returns 403 account_suspended - including read-only endpoints. Hosted checkout pages and payment links also stop working.

{
  "error": {
    "message": "This merchant account has been suspended. Contact support@paybridgenp.com to resolve.",
    "type": "account_error",
    "code": "account_suspended",
    "request_id": "req_...",
    "suspension": {
      "suspended_at": "2026-04-20T10:00:00.000Z",
      "reason": "Violation of terms of service"
    }
  }
}

Contact support@paybridgenp.com to appeal or resolve the suspension.

Handling errors in code

import { PayBridgeNP, AuthenticationError, RateLimitError, InvalidRequestError } from "@paybridge-np/sdk";

const paybridgenp = new PayBridgeNP({ apiKey: process.env.PAYBRIDGENP_API_KEY });

try {
  const payment = await paybridgenp.payments.retrieve("pay_abc123");
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Re-prompt for credentials
  } else if (err instanceof RateLimitError) {
    // Back off and retry after err.retryAfter seconds
  } else if (err instanceof InvalidRequestError) {
    // Bad input - log err.code and err.message
  } else {
    throw err;
  }
}

import paybridge_np
from paybridge_np.errors import AuthenticationError, RateLimitError, InvalidRequestError

paybridgenp = paybridge_np.PayBridgeNP(api_key=os.environ["PAYBRIDGENP_API_KEY"])

try:
    payment = paybridgenp.payments.retrieve("pay_abc123")
except AuthenticationError:
    # Re-prompt for credentials
    pass
except RateLimitError as e:
    # Back off and retry
    pass
except InvalidRequestError as e:
    # Bad input - log e.code and e.message
    pass

use PayBridgeNP\PayBridgeNP;
use PayBridgeNP\Exceptions\AuthenticationException;
use PayBridgeNP\Exceptions\RateLimitException;
use PayBridgeNP\Exceptions\InvalidRequestException;

$paybridgenp = new PayBridgeNP(['apiKey' => $_ENV['PAYBRIDGENP_API_KEY']]);

try {
    $payment = $paybridgenp->payments->get('pay_abc123');
} catch (AuthenticationException $e) {
    // Re-prompt for credentials
} catch (RateLimitException $e) {
    // Back off and retry
} catch (InvalidRequestException $e) {
    // Bad input
}

Migrating from the flat envelope

If you have integration code written before the new envelope, here is the upgrade path. The change is breaking - upgrade your SDK and any direct error parsing in lockstep.

Old shape

{
  "error": "Invalid API key",
  "code": "unauthorized"
}

New shape

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "api_key_invalid",
    "request_id": "req_..."
  }
}

What changed

error is now an object instead of a string. Reading response.error directly will give you [object Object] instead of the message.
Read response.error.message for the human-readable string, response.error.type for the broad category, response.error.code for the specific identifier.
code: "unauthorized" was generic - it has been split into api_key_missing, api_key_invalid, api_key_revoked, api_key_expired so you can branch by failure mode.
Suspension fields previously at the top level (suspended_at, suspended_reason) are now nested under error.suspension.
All errors now include error.request_id matching the X-Request-Id response header. Quote it in support requests.

SDK versions

The TypeScript, PHP, and Python SDKs handle this transparently when you upgrade:

Language	Pre-envelope	Post-envelope
TypeScript (`@paybridge-np/sdk`)	`< 3.0.0`	`>= 3.0.0`
PHP (`paybridge-np/sdk`)	`< 3.0.0`	`>= 3.0.0`
Python (`paybridge-np`)	`< 1.0.0`	`>= 1.0.0`

Overview

Checkout

Payment Links

Payments

Refunds

Webhooks

Account

Billing

Providers

SMS

Fields

Error types

HTTP status codes

Error codes

Authentication

Resources

Billing

Plans, quotas, and availability

Validation + rate limiting

The `account_suspended` error

Handling errors in code

Migrating from the flat envelope

Old shape

New shape

What changed

SDK versions

​Fields

​Error types

​HTTP status codes

​Error codes

​Authentication

​Resources

​Billing

​Plans, quotas, and availability

​Validation + rate limiting

​The account_suspended error

​Handling errors in code

​Migrating from the flat envelope

​Old shape

​New shape

​What changed

​SDK versions

Fields

Error types

HTTP status codes

Error codes

Authentication

Resources

Billing

Plans, quotas, and availability

Validation + rate limiting

The `account_suspended` error

Handling errors in code

Migrating from the flat envelope

Old shape

New shape

What changed

SDK versions