Error Handling

Your payment errors should fail closed. If the agent cannot verify a seller, fit a payment inside policy, sign a guarantee, or connect the payment to the task, it should stop or ask for approval instead of spending blindly.

Common error categories

Error	Meaning	Your response
Unsupported network	Seller requires a network your client has not registered.	Skip, choose another seller, or add the network intentionally.
Missing collateral	Wallet cannot back the payment guarantee.	Add collateral or lower the task budget.
Price over limit	Seller price exceeds policy.	Ask for approval, choose another seller, or stop.
Seller mismatch	Domain, route, or `payTo` address does not match expectations.	Do not sign. Treat as suspicious.
Invalid signature	Payment signing failed or produced an invalid payload.	Retry only after checking signer and network configuration.
Seller verification failure	Seller rejected the payment retry.	Log the failure and avoid repeated automatic retries.
Task budget exhausted	The agent has spent its allowed budget.	Stop or ask for a higher budget.

For collateral, network, or wallet issues, inspect your account in 4mica dashboard before retrying.

Retry rules

Do not retry forever. Automated retries can turn a small issue into unexpected spend or noisy traffic. Use strict retry rules that separate temporary transport failures from payment or policy decisions.

Situation	Retry behavior
Network timeout	Retry with backoff and a small attempt limit.
Policy failure	Do not retry automatically. Choose a different seller, get a lower price, or ask for approval.
Over-budget payment	Stop before signing and ask for more budget.
Seller mismatch	Do not retry. Treat the mismatch as suspicious until you verify it.
Seller verification failure	Retry only after checking signer, network, request ID, and seller configuration.

Always record the final failure reason in the task log. If retries create duplicate-looking activity, stop the agent and share the request IDs with support.

Never let retries bypass policy. A retry should repeat a valid attempt, not turn a blocked payment into an approved one.

User-facing status

Keep payment state understandable. You should be able to tell whether the agent needs approval, lacks collateral, hit a blocked seller, failed during signing or verification, exhausted its budget, or successfully received a paid response. Use stable status names so your UI, logs, and support process speak the same language.

Status	When to show it
`needs_approval`	The agent found a payment that exceeds policy.
`insufficient_collateral`	The wallet cannot back the payment guarantee.
`blocked_seller`	Your policy does not allow this seller.
`payment_failed`	Signing, guarantee issuance, or seller verification failed.
`budget_exhausted`	The task reached its spending limit.
`paid`	The request was paid and a response was received.

What you should log

Log enough to debug without guessing. The payment record should connect the task, request, seller, amount, policy, failure reason, retry count, approval state, and final outcome.

Log field	Purpose
Task ID and request ID	Connects the payment failure to the workflow.
Seller domain and `payTo` address	Shows who the agent tried to pay.
Amount, network, and asset	Shows what the agent tried to authorize.
Policy version	Explains which rules allowed or blocked the attempt.
Failure reason and retry count	Shows why the request stopped and whether retries were controlled.
Approval state and final outcome	Shows whether a person was asked and what happened next.

Getting Started

Quick Start

Background

Core Concepts

Buyer

Seller

SDKs

Webhooks

API Reference

Common error categories

Retry rules

User-facing status

What you should log

​Common error categories

​Retry rules

​User-facing status

​What you should log

Common error categories

Retry rules

User-facing status

What you should log