Facilitator Service API errors - Circle Docs

For error response shapes and general errors that can be returned by any Circle API, see API errors.

Verify and settle reasons

These reason strings appear in /verify responses as invalidReason and in /settle responses as errorReason.

Reason	Cause
`eip2612_asset_mismatch`	The permit `asset` doesn’t equal `permitted.token`
`eip2612_deadline_expired`	The permit `deadline` is less than 10 seconds away
`eip2612_from_mismatch`	The permit `from` doesn’t equal `permit2Authorization.from`
`eip2612_spender_not_permit2`	The permit `spender` isn’t Permit2
`insufficient_funds`	The buyer’s USDC balance is too low
`invalid_eip2612_extension_format`	The permit extension is partly filled, malformed, or its signature isn’t 65 bytes
`invalid_exact_evm_payload_authorization_valid_after`	`validAfter` is in the future: the authorization is not yet valid
`invalid_exact_evm_payload_authorization_valid_before`	`validBefore` has passed: the authorization has expired
`invalid_exact_evm_payload_authorization_value_mismatch`	The signed `value` doesn’t equal `paymentRequirements.amount`
`invalid_exact_evm_payload_recipient_mismatch`	The authorization `to` doesn’t equal `payTo`
`invalid_exact_evm_payload_signature`	The signature doesn’t match `from`
`invalid_network`	The `network` isn’t supported or doesn’t match the asset
`invalid_payload`	The `paymentPayload` is malformed or missing required fields
`invalid_payment_requirements`	`paymentRequirements` differs from `accepted`, including the amount on `/verify`
`invalid_permit2_recipient_mismatch`	`witness.to` doesn’t equal `payTo`
`invalid_permit2_signature`	The signature doesn’t match `from`
`invalid_permit2_spender`	`spender` isn’t the x402 Permit2 proxy
`invalid_transaction_state`	The authorization reuses a nonce that already settled
`invalid_upto_evm_payload_settlement_exceeds_amount`	On `/settle`, the actual amount exceeds the signed maximum
`invalid_x402_version`	The x402 version in the request isn’t supported
`permit2_2612_amount_mismatch`	The permit `amount` doesn’t equal the signed Permit2 maximum
`permit2_amount_mismatch`	On `/verify`, the signed `permitted.amount` doesn’t equal `paymentRequirements.amount`
`permit2_deadline_expired`	`deadline` is less than 10 seconds away
`permit2_invalid_nonce`	The Permit2 nonce is already used onchain
`permit2_not_yet_valid`	`witness.validAfter` is in the future
`permit2_simulation_failed`	The allowance is short and the permit can’t be used: its nonce is stale or its signature is invalid
`permit2_token_mismatch`	`permitted.token` doesn’t equal `asset`
`unsupported_scheme`	The `scheme` isn’t `exact` or `upto`
`upto_facilitator_mismatch`	`witness.facilitator` isn’t an active Circle facilitator for the network

Status reasons

This reason string appears in /status responses as reason.

Reason	Cause
`outcome_unknown`	Facilitator Service couldn’t determine whether the payment reached a terminal state

HTTP status errors

Some errors use an HTTP status instead of a 200 result.

Status	Cause
`401`	The request has no Circle API key and no seller proof
`403`	`/settle` called with a seller proof instead of a Circle API key
`403 authorization_expired`	`deadline` passed before Facilitator Service submitted the transfer
`409`	The `/settle` call conflicts with an existing payment. See Repeat settlements for the specific conflict modes
`412 permit2_allowance_required`	The balance covers the amount, but the Permit2 allowance doesn’t and the payment has no permit. Never returned for a `0` settlement. On `/settle`, applies only before a payment exists
`503`	Facilitator Service is temporarily at capacity or a dependency is unavailable. Retry with backoff