Skip to main content

​
HTTP Status Codes

The facilitator uses standard HTTP status codes to indicate request outcomes:
​
200 OK
Request processed successfully. Check response body for actual result.Important: Most payment validation failures return 200 with success: false in the response body. This includes signature failures, invalid amounts, wrong recipients, etc. The facilitator treats these as “successful API calls with failed payments” rather than HTTP errors.POST /accepts and GET /supported always return 200, even if handlers fail.
​
400 Bad Request
Request-level validation failures: malformed JSON, missing required fields, invalid base64 encoding.Does NOT include payment validation errors (those return 200 with success: false).
​
500 Internal Server Error
Server infrastructure errors: thrown exceptions from RPC/network failures, transaction signing failures, or other unexpected server-side errors.Does NOT include blockchain transaction failures (those return 200 with success: false).

​
Error Response Format

For settlement errors, the response follows the standard format: 
{
  "success": false,
  "error": "Detailed error description",
  "txHash": null,
  "networkId": null
}

​
Common Errors by Endpoint

​
POST /accepts

Error Message PatternStatusCauseSolution
couldn't parse required response: ...400Request validation failed (missing/invalid fields)Include required fields: x402Version (integer) and accepts (array)
Note: /accepts always returns 200. Handler failures are logged but don’t cause request errors.

​
POST /settle

​
General Errors

Error MessageStatusCauseSolution
couldn't validate request: ...400Request validation failedInclude required fields: x402Version, paymentHeader, paymentRequirements
couldn't validate x402 payload: ...400Payment payload validation failedVerify payload structure and base64 encoding
no matching payment handler found400No handler supports the payment scheme/networkVerify scheme and network are supported via /supported endpoint

​
Solana Errors

Error MessageStatusCauseSolution
Invalid transaction200Transaction validation failedReview transaction structure, fee payer, amounts, and recipients. Response has success: false. Check server logs for specific details
Transaction simulation failed200Transaction would fail on-chainResponse has success: false. Verify token accounts exist, have sufficient balance, and all addresses are correct
Transaction confirmation timeout200Transaction not confirmed within 30 secondsResponse has success: false. Transaction may still confirm. Check on-chain status before retrying
Transaction failed: ...200Transaction submitted but failed on-chainResponse has success: false. Check transaction on Solana Explorer for failure details
Solana Validation Note: Most Solana validation failures (fee payer mismatch, invalid amounts, wrong recipients, etc.) result in the generic "Invalid transaction" error with HTTP 200 and success: false. Specific validation details are logged server-side but not exposed in API responses.

​
EVM Errors

Error MessageStatusCauseSolution
Invalid payload: ...200EVM payload validation failedResponse has success: false. Check payload structure matches EVM exact payment format
Invalid signature200EIP-712 signature verification failedResponse has success: false. Verify EIP-712 domain, types, and message match exactly
Invalid from address200from address is not valid Ethereum addressResponse has success: false. Verify from address is valid and properly formatted
Payment authorized to wrong address200Authorization to doesn’t match payToResponse has success: false. Ensure authorization to field matches merchant address
Incorrect payment amount200Authorization value doesn’t match maxAmountRequiredResponse has success: false. Verify amount matches requirements exactly
Authorization not yet valid200Current time < validAfterResponse has success: false. Wait until authorization becomes valid or create new one
Authorization expired200Current time > validBeforeResponse has success: false. Create new authorization with fresh timestamps
Nonce already used200Nonce found in local cache (checked before on-chain)Response has success: false. Generate new random nonce
Authorization already used on-chain200Nonce was already consumed on-chainResponse has success: false. Generate new random nonce (32 bytes) for each payment
Wallet client is not configured with a local account200Internal facilitator configuration errorResponse has success: false. This is a server-side issue - contact facilitator operator
Transaction failed200transferWithAuthorization call failedResponse has success: false. Check token balance is sufficient and contract supports EIP-3009

​
GET /supported

GET /supported always returns 200 with a kinds array. Handler failures are logged but don’t cause request errors. If all handlers fail, returns an empty array.

​
See Also