Errors & Edge Cases

This page documents the common HTTP and profile-specific errors that can occur when implementing or using the FX402 R402 profile.

Each error includes a short description and recovery strategy.

⚠️ HTTP-Level Errors

Code	Meaning	Recovery
402 Payment Required	Resource is gated; client must pay according to R402 spec.	Display tiers and prompt user to complete payment.
400 Bad Request	Invalid or missing payment data (malformed JSON, wrong tier).	Retry with corrected payload.
401 Unauthorized	Missing or invalid JWT receipt.	Request new payment or verify JWT signature.
403 Forbidden	Access expired or rights not sufficient.	Renew rental or upgrade to a longer tier.
404 Not Found	Resource not recognized.	Verify `resource` identifier or endpoint URL.
409 Conflict	Duplicate payment attempt detected.	Retry after nonce refresh.
410 Gone	Resource permanently removed.	Stop retrying; asset retired.
429 Too Many Requests	Rate limit exceeded.	Backoff and retry after delay.
500 Internal Server Error	Unexpected server failure.	Retry later or contact operator.
502 / 503 / 504	Upstream facilitator or blockchain node unavailable.	Retry with exponential backoff.

🧩 R402-Specific Errors

Code	Field	Description	Suggested Action
`R402_INVALID_TIER`	`tier_id`	The requested tier does not exist or has expired.	Refresh tiers and prompt user to reselect.
`R402_INVALID_PROOF`	`payment_proof`	Invalid or unverifiable transaction proof.	Ensure transaction finalized on-chain.
`R402_EXPIRED_RECEIPT`	`receipt`	The license has expired.	Prompt for renewal.
`R402_MISMATCHED_RESOURCE`	`resource`	Receipt does not match requested asset.	Check resource ID and retry.
`R402_UNSUPPORTED_CHAIN`	`pay_to.chain`	Payment chain unsupported by the server.	Switch to supported chain (e.g., Solana).
`R402_DUPLICATE_NONCE`	`nonce`	The same nonce was reused.	Request new pricing payload.
`R402_FACILITATOR_ERROR`	`facilitator`	Verification service unavailable or invalid signature.	Retry later or fallback to honor mode.
`R402_TIER_EXPIRED`	`usage.tiers`	Tier pricing expired or updated.	Refresh metadata and display new prices.

🧱 Common Edge Cases

1. Payment Succeeds but Resource Fails to Unlock

Cause: network delay between blockchain confirmation and facilitator verification.
Fix: retry after short delay; facilitator will reconcile once transaction confirmed.

2. JWT Receipt Lost or Corrupted

Cause: local storage cleared or user switched device.
Fix: facilitator can re-issue a receipt based on transaction proof.

3. Out-of-Sync Metadata

Cause: cached r402 metadata mismatched with live server.
Fix: always refresh before payment; ignore cached tiers older than 24h.

4. Clock Drift / Expiration Issues

Cause: client clock offset makes valid_until appear expired.
Fix: use network time (NTP or server timestamp) for comparison.

🧭 Developer Tips

Always validate both HTTP status and R402 error codes.
Log every 402 interaction for auditability.
Implement exponential backoff for all facilitator requests.
Never expose private facilitator signing keys in client apps.