MCP tool errors
Payment-method and transaction tools return JSON in a text content block. CheckisError, then parse the body:
nextStep is a plain-language instruction for what to do. Transaction errors can also include details, with retryable, retryWithSameIdempotencyKey and a retry delay. Compatibility and spending-limit tools use their own error shapes.
Transaction error codes
Authentication, scope and permission errors are returned when a key is missing, invalid or lacks a permission.
A timeout does not mean nothing happened. For what to retry and when, see Recover without buying twice.
Creating a transaction with no saved card
If you create a transaction withPOST /v1/transactions without naming a card, Sapiom uses the buyer’s default card. If the buyer has no active card, the request returns 400 with "code": "no_saved_card" and nothing is created. Send the buyer a setup link, then create the transaction again.
Relay refusals
When the relay refuses, nothing was sent to the payment processor. Browser Pay’srefused event carries one of these reasons:
Browser Pay failures
Browser Pay’sfailed event has one of these reasons. For the next step, refer to Recover without buying twice.
REST error responses and the full error inventory to be documented.