Error Handling

verify() and settle() throw on failure rather than returning a falsy result — there is no { isValid: false } shape to check. Wrap calls in try/catch and use the error classes below to decide how to respond.

Error classes

Class	When it’s thrown
`X402FacilitatorConfigError`	Missing required config (`apiKey` or `orgId`) — thrown synchronously by the constructor, before any network call.
`X402FacilitatorNetworkError`	The network request itself never completed (DNS failure, timeout, connection refused). Automatically retried — see below.
`X402FacilitatorError`	The facilitator returned an unexpected HTTP status. Carries a `.statusCode` property.

import {
  X402FacilitatorClient,
  X402FacilitatorError,
  X402FacilitatorConfigError,
  X402FacilitatorNetworkError,
} from "@xentfi/x402-facilitator-sdk";

try {
  const facilitator = new X402FacilitatorClient({ apiKey, orgId });
  await facilitator.verify(payload, requirement);
} catch (err) {
  if (err instanceof X402FacilitatorConfigError) {
    // apiKey/orgId missing — a setup bug, fix before deploying
  } else if (err instanceof X402FacilitatorNetworkError) {
    // exhausted retries against a genuine network failure
  } else if (err instanceof X402FacilitatorError) {
    console.log(err.statusCode, err.message);
  }
}

HTTP status mapping

The facilitator’s error handler returns consistent error responses with these status codes:

Code	Meaning
`402`	Payment or verification failed (invalid signature, expired authorization, amount/recipient mismatch).
`400`	Bad request or validation error.
`401`	Authentication error — invalid or missing `apiKey`/`orgId`.
`403`	Authorization error — credentials valid but insufficient permission.
`404`	Resource not found.
`500`	Internal server error.

A 402 response from /verify or /settle is a normal, expected outcome for an invalid or expired payment — not a bug in your integration. Surface err.message back to the payer in your own 402 challenge response’s error field (see Resource Server Guide) so their agent can retry correctly.

Automatic retries

Requests are retried automatically on X402FacilitatorNetworkError (i.e. the request never got a response at all) with exponential backoff and jitter:

Attempt	Base delay	With jitter (up to +25%)
1	—	immediate
2	250ms	~250–312ms
3 (final)	500ms	~500–625ms

Requests that do get a response — including 402s and other HTTP error statuses — are not retried automatically, since a 402 or 4xx is a deterministic outcome that won’t change on retry without a different payload.

Common scenarios

X402FacilitatorConfigError: apiKey is required

Thrown immediately by the constructor if apiKey (or orgId) is missing. Check your environment variables (WAAS_API_KEY, WAAS_ORG_ID) are set before constructing X402FacilitatorClient.

402 from verify() — invalid signature

The signed EIP-712 message doesn’t match what the contract/facilitator expects — usually a wrong Eip3009TokenDomain (see Signing Reference) or a payload that was tampered with in transit.

402 from verify() — expired authorization

validBefore has passed. Either the payer waited too long between signing and sending, or validitySeconds was set too short for the round trip. Have the payer re-sign a fresh authorization.

402 from settle() — nonce already used

The same (from, nonce) pair was already submitted on-chain. If you intentionally reuse deterministic nonces for idempotency, this is expected on a genuine retry of an already-settled payment — check xentfi_get_payment-style transaction history (or your own settlement log) before treating it as an error.

401 Unauthorized

Invalid or revoked apiKey/orgId. Verify both against the dashboard.

See API Reference: Error Handling for the platform-wide error code and status conventions this builds on.

Getting Started

Guides

Reference

Error classes

HTTP status mapping

Automatic retries

Common scenarios

​Error classes

​HTTP status mapping

​Automatic retries

​Common scenarios

Error classes

HTTP status mapping

Automatic retries

Common scenarios