Errors

Errors use a consistent shape:

{ "error": { "code": "amount_mismatch", "message": "amount (100) does not equal items + shipping + tax (12430)", "details": { "expected": 12430 }, "request_id": "req_…" } }

HTTP	Code	Meaning
400	invalid_request	Body failed validation; see details
400	invalid_json	Body is not JSON
400	idempotency_key_required / idempotency_key_invalid	Missing or malformed key
401	authentication_required / invalid_api_key	Missing or wrong key
401	api_key_revoked / api_key_expired	Key no longer valid
403	insufficient_scope	Key lacks the scope
403	live_disabled	Live operations are not available
404	not_found	Not found for this merchant and environment
409	no_active_connection	No active provider connection
409	order_already_paid / order_mismatch	Order reference conflict
409	payment_not_refundable / refund_exceeds_available	Refund not allowed
413	payload_too_large	Body over 64 KB
422	amount_mismatch / amount_too_large	Totals invalid
422	return_url_not_approved / cancel_url_not_approved	URL not on an approved website
422	no_payment_methods	Requested methods not approved
422	idempotency_key_reused	Same key, different body
422	crypto_destination_required	USDC refund needs a verified destination
429	rate_limited	Slow down
500	internal_error	Retry with the same idempotency key