Gateway should not silently fall back to free tier when x402 payment fails

[crtahlin]

Problem

Feedback from CLI developer testing x402 integration:

The gateway should:

• NOT return 201 if x402 payment fails - return an error (e.g., 402 or 500)
• Or clearly indicate in response that free tier was used instead of paid
• Don't silently fall back to free tier when payment fails

Current Behavior

When x402 payment fails or doesn't settle, the gateway may:

1. Return 201 success without indicating payment wasn't processed
2. Silently fall back to free tier without clear indication in response

Expected Behavior

1. When X-PAYMENT header is provided but verification fails → return 402 (already implemented)
2. When X-PAYMENT header is provided but settlement fails → return appropriate error, don't silently succeed
3. When free tier is used → include clear indication in response body (not just header)
4. Never silently fall back to free tier when paid tier was intended

Investigation Points

1. Check if CLI is sending X-Payment-Mode: free header that triggers unintended free tier
2. Check settlement failure handling (currently logs error but returns success)
3. Ensure X-Payment-Mode: free-tier response header is being checked by CLI
4. Consider adding payment status to response body for clarity

Related

• x402 Phase 1 implementation
• Parent issue: datafund/provenance-fellowship#23

[crtahlin]

Status update: This may be partially addressed. The x402 middleware now includes:

• X-Payment-Mode: free-tier header when free tier is used
• Payment verification before proceeding

However, need to verify with CLI developer if the silent fallback issue is resolved. The current implementation should:

1. Return 402 if payment header provided but invalid
2. Include clear indication when free tier is used

Testing needed: CLI developer should retest to confirm behavior is acceptable.