Error Codes

All API errors return a consistent JSON shape with a machine-readable code and a human-readable message.

error response

{
  "error": {
    "code": "quote_expired",
    "message": "Quote has passed its expiry window"
  }
}

Use the code field for programmatic error handling. The message is for debugging and may change.

Payment errors

HTTP	Code	Description	Common cause
402	payment_required	No payment token provided.	Caller hit a paid endpoint without a settlement token.
410	quote_expired	Quote has passed its expiry window.	Default expiry is 10 minutes. Pass expires_in_seconds to extend.
410	settlement_expired	Redeem window has elapsed.	Vendor did not redeem within the configured window.
409	settlement_already_redeemed	Settlement was already consumed.	Redeem is single-use. Retrying returns this if already succeeded.
409	quote_already_paid	This quote has already been settled.	Consumer tried to settle the same quote twice.
409	payment_in_progress	A settlement is already being processed.	Concurrent settle call with same payment_attempt_id.
500	payment_failed	On-chain transaction failed.	Solana transaction error. Check balance and delegation status.
400	invalid_quote_amount	Quote amount is invalid.	Amount must be a positive integer string in USDC micro-units.
400	vendor_net_too_low	Vendor net amount below minimum after fees.	Increase quote_amount so the net exceeds the platform minimum fee.

HTTP	Code	Description	Common cause
400	consume_balance_exhausted	No remaining balance to consume.	Total consumed equals the settlement amount.
409	consume_refund_in_progress	Cannot consume while a refund is pending.	Wait for the refund to resolve before consuming more.

HTTP	Code	Description	Common cause
400	consumer_wallet_required	Consumer does not have a wallet.	Provision or register a wallet before settling.
400	vendor_wallet_required	Vendor service has no wallet.	Vendor must have a wallet to receive payments.
400	wallet_required	A wallet is required for this operation.	Provision or register a wallet first.
404	wallet_not_found	Wallet does not exist.	Check the wallet ID.
409	duplicate_wallet	Wallet address already registered.	This Solana address is already linked to an account.
500	wallet_provision_failed	Turnkey wallet creation failed.	Retry. If persistent, check Turnkey service status.
400	wallet_not_delegated	Wallet has no active delegation.	Call POST /wallets/:id/delegate before settling.
400	delegation_required	Spending delegation must be set up.	Consumer wallet needs delegation for the platform to transfer.
500	delegation_failed	On-chain delegation transaction failed.	Retry. Check wallet balance for SOL fees.
400	consumer_ata_required	Consumer USDC token account missing.	Usually auto-created during settle. May indicate a network issue.

HTTP	Code	Description	Common cause
400	insufficient_balance	Wallet does not have enough USDC.	Fund the wallet via POST /deposits/fiat or POST /dev/fund (devnet).
403	spending_limit_exceeded	Delegate key spending limit reached.	Increase limits via PATCH /delegates/:id or wait for the window to reset.
400	self_transfer_blocked	Cannot pay yourself.	Consumer and vendor wallets must be different.

HTTP	Code	Description	Common cause
401	invalid_token	Token is missing, expired, or malformed.	Refresh your JWT or check your API key.
401	email_auth_failed	Magic link verification failed.	Link may be expired (default 10 min) or already used.
401	passkey_registration_failed	WebAuthn registration failed.	Challenge may be expired or the response is invalid.

HTTP	Code	Description	Common cause
404	account_not_found	Account does not exist.	Call POST /accounts to create one.
404	service_not_found	Service does not exist.	Check the service_id.
404	quote_not_found	Quote does not exist.	Quote may have expired and been cleaned up.
404	settlement_not_found	Settlement does not exist.	Check the settlement_id.
404	delegate_not_found	Delegate key does not exist.	Check the delegate ID or it may have been revoked.
404	withdrawal_not_found	Withdrawal does not exist.	Check the withdrawal ID.
404	refund_not_found	Refund does not exist.	Check the refund ID.
404	deposit_not_found	Deposit does not exist.	Check the deposit ID.
404	fee_terms_not_found	Fee terms not configured.	Contact support — platform fee terms must exist.

HTTP	Code	Description	Common cause
409	duplicate_service_slug	Service slug already taken.	Choose a different name for your service.
400	withdrawal_not_pending	Withdrawal is not in pending state.	Only pending withdrawals can be approved or cancelled.
409	withdrawal_already_approved	Withdrawal was already approved.	Check withdrawal status — it may already be processing.
410	withdrawal_approval_expired	Approval window has elapsed.	Create a new withdrawal intent.
400	refund_not_pending	Refund is not in pending state.	Only pending refunds can be submitted or cancelled.
400	settlement_not_refundable	Settlement cannot be refunded.	Settlement must be redeemed before refunding.
400	refund_amount_exceeds_settlement	Cumulative refund exceeds original payment.	Reduce the refund amount.
409	service_has_usage	Service has existing settlements.	Deactivate instead of deleting services with history.
400	key_not_revealable	Key cannot be revealed.	Key reveal may already be in progress or recently used.

HTTP	Code	Description	Common cause
503	signer_unavailable	Transaction signing service is down.	Transient. Retry after a few seconds.
500	tx_validation_failed	Transaction failed signer validation.	Internal error. Contact support if persistent.
501	not_implemented	Feature is not yet available.	This endpoint or option is planned but not shipped.