Errors
Standard error envelopes avoid provider raw errors and preserve support correlation.
Envelope
Errors use stable AICardAPI codes, concise messages and request_id. Provider raw errors are not public error codes.
{"error":{"code":"idempotency_conflict","message":"request body differs"},"request_id":"req_demo"}Auth and permission errors
Treat unauthorized and forbidden responses as action blockers. Do not retry by switching merchant_id values; sign in with the correct UI principal or use the correct Merchant API key scope.
Provider-gated errors
capability_unavailable and provider_required responses mean the requested action is fail-closed until internal provider evidence, runtime configuration and fallback conditions are ready. The MVP does not expose a merchant capability catalog.
Support guidance
Share request_id, endpoint, timestamp and non-sensitive context. Do not attach API keys, webhook secrets, full card data or provider raw payloads.