Why does an x402 facilitator settle call time out?

A facilitator HTTP deadline can expire while settlement is still progressing. Network latency, chain confirmation time and facilitator processing can outlast the client timeout. A settle timeout is therefore an indeterminate outcome unless the implementation proves that no transaction was broadcast.

What is the x402 HTTPFacilitatorClient default timeout now?

The official x402 TypeScript, Python and Go HTTP facilitator clients were updated in September 2026 to use a 90-second default per-request timeout instead of 30 seconds. Each SDK still allows an explicit shorter or longer application-level override within its supported configuration surface.

Does a 90-second x402 timeout guarantee settlement?

No. The 90-second default reduces premature client-side timeout failures, but it does not guarantee chain confirmation, facilitator availability, resource delivery or final settlement. Applications still need an unresolved state and reconciliation logic.

Should an x402 client retry immediately after a settlement timeout?

Do not create a fresh payment blindly. Preserve the payment identity, facilitator response, transaction hash when available and network; reconcile the original economic action first. Only create a new authorization after the prior payment is known not to have occurred or the facilitator documents a duplicate-safe retry path.

What does x402 settlement_pending mean?

settlement_pending is a non-terminal settlement result for a broadcast whose confirmation could not be established before the receipt wait ended. The payment may still confirm, so pending must not be collapsed into ordinary payment failure.

Editorial

Research guide · x402 payment operations · updated 13 September 2026

x402 facilitator timeout: 90s SDK defaults, settlement_pending and safe retries

If an x402 settle() call times out, the dangerous assumption is that nothing happened. The official TypeScript, Python and Go SDKs have now moved their HTTP facilitator-client defaults from 30 seconds to 90 seconds so long settlements have more time to complete. That reduces one source of false failure, but it does not remove the payment-reconciliation problem: a timeout can still occur after the economic action has started.

Published 13 September 2026 · refreshed with official SDK changes merged 7–8 September 2026 · sources checked 13 September 2026

90s default

official TypeScript, Python and Go facilitator HTTP clients now wait longer by default

pending ≠ failed

a timeout or settlement_pending result can represent an unresolved economic action

reconcile first

do not convert transport uncertainty into a second authorization

What changed

x402's official SDKs raised the default facilitator deadline from 30 seconds to 90 seconds

The September SDK changes are unusually useful diagnostic evidence because they align three official implementations around the same failure mode: a facilitator request, especially settle(), can legitimately take longer than the old 30-second client default. The change is an accommodation for long settlement calls, not a protocol guarantee that every valid payment will finish inside 90 seconds.

Official SDK	New default	Merged change	Operational meaning
TypeScript	90,000 ms	PR #3392	Also buffers Hono/Next protected response bodies until settlement completes.
Python	90.0 s	PR #3409	Raised HTTPFacilitatorClientBase from 30 seconds; explicit timeout overrides still work.
Go	90 s	PR #3408	Raised the default from 30 seconds; FacilitatorConfig.Timeout still overrides it.

TypeScript's change also fixed a related delivery-ordering problem in the Hono and Next adapters: the protected response body is buffered before settlement and only returned after settlement succeeds. That is separate from the timeout value, but it reinforces the same boundary — useful delivery and confirmed payment must not be allowed to drift apart.

Timeout tuning

Do not treat 90 seconds as a magic correctness threshold

Raising the client deadline helps when the previous failure was simply “the facilitator needed longer than 30 seconds.” It does not solve a facilitator-side deadline, RPC timeout, chain congestion, dropped response, late confirmation or application delivery failure. Your own latency budget may also require a shorter deadline; all three SDKs keep an explicit override.

A good operator therefore separates request deadline from payment finality. The request deadline answers how long the caller is willing to hold an HTTP operation open. Finality answers whether the transfer actually happened. When those clocks disagree, the purchase must enter an unresolved state rather than automatically spending again.

TypeScript

new HTTPFacilitatorClient({
  timeoutMs: 45_000
})

Python

FacilitatorConfig(
  timeout=45.0
)

FacilitatorConfig{
  Timeout: 45 * time.Second,
}

These examples show the relevant override names, not recommended production values. Pick a deadline from your application SLO, facilitator behavior and settlement rail; preserve reconciliation when that deadline expires.

Protocol boundary

A broadcast timeout is an uncertainty state, not a rejection

x402 v2 defines settlement_pending for a settlement transaction that was broadcast but whose confirmation could not be established — for example because the receipt wait timed out. A pending result carries the transaction hash and network so the caller has authoritative evidence to reconcile rather than blindly generating another payment.

The Python SDK had already moved EVM exact, upto and batch-settlement receipt-wait failures into this non-terminal state in version 2.20.0. The newer 90-second HTTP-client changes attack an earlier layer of the same operational problem: do not prematurely turn a slow settlement into a terminal transport error.

Neither behavior eliminates the need to model payment and useful delivery separately. A buyer can pay and fail to receive the protected result; a seller can verify a payment yet still require confirmed settlement before releasing value. Autonomous procurement systems need durable evidence for both verdicts.

Reconciliation runbook

Persist the purchase as unresolved until the economic effect is known

Observed state	Operator action	Safety rule
No broadcast evidence	Evaluate the returned terminal reason and facilitator contract.	Do not invent an on-chain outcome.
HTTP timeout / unknown	Persist the logical purchase, payment fingerprint and timeout evidence; block fresh authorization.	Timeout is not proof of failure.
settlement_pending	Persist transaction hash and network and reconcile the already-broadcast action.	Pending is not failed.
Expected transfer confirmed	Match network, asset, destination and amount before marking payment settled.	Then reconcile application delivery separately.
Definitive chain failure	Use the provider's documented retry path or create a new authorization only after the original economic effect is ruled out.	A fresh payment is the last step, not the first.

Wire-level diagnosis

Seven checks before changing the timeout again

Identify which deadline fired: your HTTP client, reverse proxy, serverless platform, facilitator, RPC provider or chain receipt wait.
Record the SDK/language and effective timeout value; do not assume every deployed version has the September 90-second default.
Preserve the logical purchase identity, accepted payment requirements and signed payment fingerprint without logging reusable secrets.
Capture any SettleResponse, PAYMENT-RESPONSE, transaction hash, network and facilitator error before retry logic mutates state.
If a transaction was broadcast or the outcome is otherwise indeterminate, quarantine the purchase from fresh authorization and reconcile the original economic action.
Verify any eventual transaction against the expected network, asset, destination and amount or metered settlement amount before promoting it to settled.
Only then decide whether to retry the same settlement idempotently, recover delivery, or create a genuinely new authorization.

Pair this with the x402 payment-identifier guide for duplicate-safe logical requests and the x402 buyer-verification guide for pre-payment controls. For metered ceilings, see x402 upto billing.

Primary sources

Qualified buyers can inspect zFinia's machine-service catalogue at /api.