Errors

title: "Errors" description: "Every BchainPay error has a stable code, a human-readable message, and a documented HTTP status." section: "API reference" order: 1 updated: "2026-04-18" sourcePath: "content/docs/api/errors.mdx"

The BchainPay API returns conventional HTTP status codes and a JSON body with a stable error code. Always switch on code, not message (messages may change).

Error envelope

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_network",
    "message": "Network 'avalanche' is not supported.",
    "param": "network",
    "request_id": "req_8H2x...91"
  }
}

Field	Type	Required	Description
type	string	required	Coarse category: `invalid_request`, `auth`, `rate_limit`, `idempotency`, `api_error`.
code	string	required	Stable machine-readable code. Switch on this.
message	string	required	Human-readable explanation. Safe to log; not safe to display to end users.
param	string	optional	Field that caused the error, when applicable.
request_id	string	required	Echo this back to support to speed up triage.

HTTP status codes

Status	Meaning
`200`	OK.
`201`	Resource created.
`202`	Accepted; the work is queued (e.g. a withdrawal).
`400`	Invalid request — usually bad input.
`401`	Authentication failed.
`403`	Authenticated but not authorized.
`404`	Resource does not exist.
`409`	Conflict (idempotency reuse, locked pocket).
`422`	Semantically invalid (e.g. address/network mismatch).
`429`	Rate limited.
`5xx`	BchainPay had a problem. Retry with backoff and jitter.

Common codes

Code	Status	Meaning
`invalid_api_key`	`401`	Bearer token missing, malformed, or revoked.
`forbidden_scope`	`403`	Key lacks the required permissions.
`invalid_network`	`400`	Network is not in the supported list.
`invalid_settlement_currency`	`400`	Coin is not available on that network.
`address_network_mismatch`	`422`	Destination is not valid on the pocket's network.
`address_blocked`	`422`	Destination matches a sanctioned address list.
`insufficient_balance`	`400`	Pocket balance below `amount_cents + network_fee_cents`.
`pocket_locked`	`409`	Another withdrawal is already in flight.
`idempotency_conflict`	`409`	Idempotency key reused with a different body.
`rate_limited`	`429`	Per-key rate limit exceeded. Honor `Retry-After`.