Developer›Errors

Errors.

Every error returns a structured JSON response with a machine-readable code and a human-readable message. Every error includes a request_id you can cite in support.

Error shape

error.json

{
  "error": {
    "code": "invalid_request",
    "message": "Either customerId or customerEmail is required",
    "param": "customerId",
    "request_id": "req_01HGKM4Z7WQ4X"
  }
}

Error types

`request`

The request was malformed or refers to a resource that doesn't exist or can't transition the way you asked.

invalid_request400. The body, query, or path violated the schema. The error.param field points at the offending field when applicable.
invalid_state_transition422. The resource exists but is in a state that doesn't permit the requested change (e.g. cancelling an already-canceled subscription).
not_found404. The referenced customer, subscription, payment, or wallet could not be found in this workspace.
conflict409. The request conflicts with an existing resource — most commonly a unique-constraint clash or an Idempotency-Key reuse with a different body.

`auth`

Authentication or authorization failed.

unauthorized401. The API key, session, or portal token is missing, malformed, or revoked.
forbidden403. You're authenticated but the actor lacks permission for this workspace or this action.
aal_required401. The route requires step-up (passkey re-auth). The dashboard surfaces a passkey prompt; SDKs raise StepUpRequiredError.
restricted_jurisdiction403. Merchant signup or action refused because the declared country / US-state is on the restricted list. error.metadata carries { code, name, reason }.
kyb_required403. The workspace must complete Know-Your-Business verification before this live-mode mutation can run. Submit KYB at Settings → Verification. Only enforced when KYB_REQUIRED_FOR_LIVE=1 on the platform.

`compliance`

A compliance step (KYB, attestation, jurisdiction) blocked the action.

attestation_required412. Hosted checkout requires customer self-attestation (state + age) for the merchant's product category before payment can proceed. The hosted page handles this transparently; direct API consumers must POST /v1/checkout/:id/attestation first.

`settlement`

On-chain settlement could not complete or hasn't yet.

chain_reverted422. The submitted transaction was mined but reverted on-chain — typically an allowance or balance issue at execution time.
insufficient_confirmations422. The payment was observed but doesn't yet meet the confirmation threshold for this chain. Poll, or wait for the payment.confirmed webhook.
signing_required422. The action needs a fresh wallet signature from the customer (e.g. resuming a paused subscription with a renewed allowance).

`rate_limit`

You exceeded the allowed request rate.

rate_limited429. Back off and retry. The Retry-After header is set when applicable; SDKs read it onto RateLimitError.retryAfter (number | null).

`api_error`

An unexpected error on OpenSettle's side. We page automatically.

internal_error500. Something went wrong on our side. Quote the request_id when contacting support.

API reference Webhooks