Errors

The BchainPay API uses conventional HTTP status codes and returns a consistent JSON error envelope. Always branch on code, not message — messages are human-readable and may change without notice.

Error envelope

Every error response wraps the details inside an error object:

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid",
    "details": { "field": "reason" },
    "request_id": "req_8H2xK91"
  }
}

Field	Type	Required	Description
code	string	required	Stable machine-readable error code. Always switch on this value.
message	string	required	Human-readable explanation. Safe to log but not to display to end users.
details	object	optional	Additional context when available. Typically maps a field name to the reason it failed validation.
request_id	string	required	Unique identifier for this request. Include it in support tickets to speed up triage.

HTTP status codes

Status	Meaning
`200`	OK.
`201`	Resource created.
`400`	Bad request — invalid or missing parameters.
`401`	Authentication failed.
`403`	Authenticated but insufficient permissions.
`404`	Resource does not exist.
`409`	Conflict — idempotency key reuse or invalid state transition.
`422`	Semantically invalid — e.g. unsupported currency.
`429`	Rate limited. Retry with exponential backoff.
`500`	Internal server error. Retry with backoff.
`503`	Service temporarily unavailable. Retry with backoff.

Error codes

Code	HTTP Status	Message
`invalid_request`	`400`	The request body is invalid
`missing_idempotency_key`	`400`	Idempotency-Key header is required
`unauthorized`	`401`	Invalid or missing API key
`forbidden`	`403`	Insufficient permissions
`not_found`	`404`	Resource not found
`conflict`	`409`	Resource already exists with different parameters
`invalid_state_transition`	`409`	This action is not allowed in the current state
`invalid_currency`	`422`	Currency not supported
`rate_limited`	`429`	Too many requests
`internal_error`	`500`	An internal error occurred
`price_unavailable`	`503`	Token price is currently unavailable; please retry shortly
`no_wallets_available`	`503`	No wallets available for the requested network

Handling errors

const res = await fetch("https://api.bchainpay.com/v1/payment-intents", {
  method: "POST",
  headers: { /* ... */ },
  body: JSON.stringify(payload),
});
 
if (!res.ok) {
  const { error } = await res.json();
 
  switch (error.code) {
    case "rate_limited":
      // back off and retry
      break;
    case "price_unavailable":
    case "no_wallets_available":
      // transient — retry with backoff
      break;
    case "invalid_request":
      // inspect error.details for field-level info
      console.error(error.details);
      break;
    default:
      console.error(`[${error.code}] ${error.message} (${error.request_id})`);
  }
}