API reference

Errors

Stable codes. Branch on error.code; log request_id.

JSON

{
  "error": { "code": "idempotency_conflict", "message": "Idempotency-Key was used with a different document" },
  "request_id": "0198f80c-5555-7dc1-a369-90556a64f700"
}

Requests#

Code	Status	Condition
`invalid_request`	400	Malformed JSON, missing or unknown field, wrong type, missing JSON content type, or control character. Message names the field.
`invalid_amount`	400	Syntax, precision, or sign.
`missing_idempotency_key`	400	Header absent on create.
`idempotency_conflict`	409	Key reused with a different immutable field, including attachment hash.
`payload_too_large`	413	Body exceeds the route limit.
`rate_limited`	429	Retry-After set.
`not_found, method_not_allowed`	404 / 405	Route or method.
`internal_error`	500
`database_unavailable`	503

Authentication and account#

Code	Status	Condition
`unauthorized`	401	Missing or invalid API key or session.
`identity_unauthorized`	401	Session-only route called with an API key or invalid session.
`identity_unavailable`	503	Identity provider keys unavailable; sessions cannot be verified.
`account_disabled`	403
`account_contact_required`	409	Account has no verified email.
`api_key_generation_conflict`	409	expected_generation mismatch.
`authentication_event_already_used`	409	Sign-in event already consumed.

Resources#

Code	Status	Condition
`deposit_request_not_found`	404	Missing, malformed, or foreign id.
`customer_not_found`	404
`issuer_not_found`	404
`payout_address_not_found`	404
`webhook_not_found`	404	Also: test event requested on a disabled endpoint.
`attachment_not_found`	404	Also: request has no attachment.
`issuer_name_taken`	409
`issuer_in_use`	409	Requests issued under the identity.
`issuer_email_already_verified`	409
`unsupported_chain, unsupported_token`	422	Override not served by the environment.
`webhooks_unavailable`	503	No webhook encryption key configured.

Attachments#

Code	Status	Condition
`attachment_scan_pending`	409	Scan not reported. Retry finalize with backoff.
`attachment_rejected`	422	Not a clean PDF within limits. Object deleted.
`attachment_not_ready`	409	Not finalized, rejected, expired unused, or no object uploaded.
`attachment_already_attached`	409	Belongs to another request.

Deposits and proofs#

Code	Status	Condition
`deposit_request_not_settled`	409	Proof requested before settlement.
`deposit_sender_mismatch`	409	Credited transfer from a wallet other than payer_wallet. No proof issued.
`deposit_request_not_payable`	410	Expired, settled, or closed.
`deposit_request_not_blocked`	409	Operator release on a request not in needs_attention.

Verification and wallet#

Code	Status	Condition
`invalid_deposit_link`	401	Unknown id on a payer route.
`verification_required`	401	Gated content requested without an unlocked session.
`payer_session_invalid`	401	Header missing, unknown, expired, or for another request.
`otp_invalid`	401
`otp_resend_cooldown`	429	One code per minute. Retry-After set.
`verification_not_started`	409	No outstanding code.
`verification_not_required`	409	Mode is permissionless.
`verification_method_not_applicable`	409	Email routes under merchant_session; client secret under verified_email.
`verification_persistence_unavailable`	503	Code accepted, not recorded. Retry with continuation.
`verification_unavailable`	503	No identity provider configured.
`identity_provider_unavailable`	502
`client_secret_invalid`	401	Unknown, malformed, expired, or foreign.
`client_secret_used`	409	Already exchanged.
`wallet_required`	409	QR requested before a wallet is bound.
`wallet_challenge_required`	409	No unexpired challenge on the session.
`wallet_already_bound`	409	Message names the bound wallet.
`wallet_signature_invalid`	401	Signature does not recover to wallet.