Troubleshoot payments

Troubleshoot from the outside in and preserve the operation's identity. Do not change the idempotency key, disable policy, or retry with a new payment until you know whether the prior attempt settled or fulfilled.

Fast triage

Step 1: prove route ownership

curl -i https://service.example/health
curl -i https://service.example/.well-known/agent-card.json
curl -i https://service.example/entrypoints

Check that the card's interface and entrypoint URLs use the public HTTPS origin and exactly one configured base path. A framework-local legacy route can bypass Lucid even while discovery looks correct.

/health is only liveness. If payment dependencies are unavailable while health is 200, inspect the application's private readiness check.

Step 2: capture an unpaid challenge

Use plain Fetch/curl with a stable idempotency key:

curl -i https://service.example/entrypoints/quote/invoke \
  -H 'content-type: application/json' \
  -H 'idempotency-key: troubleshoot-quote-000001' \
  --data '{"input":{"symbol":"ETH"}}'

Save the HTTP status, date, request target, sanitized body, error code, and PAYMENT-REQUIRED. Decode the challenge only in a trusted local process and verify:

• x402 version 2 and supported exact scheme;
• canonical CAIP-2 network;
• exact expected payee and decimal/base-unit amount;
• asset and facilitator combination supported by both sides;
• resource/method binding and unexpired time bounds.

Never paste a payment signature, Authorization: Payment, SIWX signature, private key, bearer token, or task access token into a decoder or issue.

Step 3: probe the facilitator/provider

Query its documented /supported endpoint with the same authentication and network environment used by Lucid. Confirm x402 version, scheme, network, asset, and any provider-specific limits. Then distinguish:

• DNS/TLS/connectivity failure;
• authentication/authorization failure;
• unsupported requirement;
• verification rejection;
• settlement rejection;
• timeout/unknown outcome;
• rate limit or provider incident.

Do not treat a brand's general network support page as proof that this account, endpoint, asset, and scheme are enabled.

Error-code reference

Error messages may contain dependency details not suitable for public clients. Expose stable codes and safe correlation IDs; keep sensitive internals in access-controlled logs.

Distinguish recording failure before and after settlement

payment_recording_failed covers more than one window:

1. Accounting could not be staged: external settlement was not started by Lucid, but invoke handler/stream/task admission may already have occurred.
2. External settlement succeeded, local commit failed: money is irreversible while a non-expiring staged batch remains counted.
3. SIWX entitlement recording failed after settlement: payment may be complete but reusable access was not recorded.

Check settlement headers/reference, staged store state, facilitator/chain, and fulfillment evidence. Never delete the staged record or issue a new charge just to clear the error.

Buyer-side checks

For an EVM buyer:

• the signer account/address is the expected dedicated wallet;
• the x402 client registered the challenge's canonical eip155:* network;
• the wallet has the correct asset and any required gas;
• policy Fetch is inside/below the x402 wrapper;
• the requirement payee is allowlisted and the amount fits every group;
• unpaid and paid requests have the same URL, method, body, and idempotency key;
• proxy/client code did not drop PAYMENT-SIGNATURE or response headers.

Lucid's convenience buyer is not a Solana signer. A Solana-capable seller challenge cannot be paid by an EVM-only client.

Adapter-specific checks

Always reproduce against the adapter directly and through the production proxy/CDN to isolate the layer.

Recovery by outcome

Escalation bundle

Include:

• UTC timestamps and sanitized trace/operation/run/task IDs;
• Lucid and package versions, release channel/commit, adapter, runtime image;
• public route and base path (without sensitive query data);
• HTTP status and stable error code;
• x402/MPP version, scheme/intent, canonical network, asset, amount, expected payee, facilitator hostname;
• whether a payment credential was sent, whether settlement evidence exists, and whether fulfillment ran;
• relevant store/provider health and sanitized external transaction reference.

Exclude all credentials, private keys, tokens, cookies, connection strings, full wallet payloads, and unredacted input/output.

Read the payment transaction model, observability contract, and durable storage guide for recovery ownership.