Request Lifecycle Overview
Every HTTPayer request progresses through a defined lifecycle, especially when payments or refunds are involved. The lifecycle is divided into five phases:- Discovery
- Payment Processing
- Upstream Execution
- Completion
- Refund Handling (if applicable)
Status Reference
Discovery Phase
| Status | Description |
|---|---|
payment_required | Client must submit a valid x402 payment (HTTP 402) |
Payment Processing
| Status | Description |
|---|---|
payment_received | Payment detected but not yet validated |
payment_validating | On-chain confirmation in progress |
processing | Upstream API call in progress |
async_processing | Long-running request (HTTP 202) |
Success Outcomes
| Status | Description |
|---|---|
success | Request completed successfully |
success_refunded | Request succeeded but user was refunded (target did not charge) |
Failure Outcomes
| Status | Description |
|---|---|
payment_failed | Payment settlement failed |
upstream_error | Target API returned an error |
internal_error | HTTPayer internal failure |
rate_limited | Daily spending limit exceeded |
validation_failed | Invalid request parameters |
Refund Lifecycle
| Status | Description |
|---|---|
refund_issued | Refund transaction sent |
refund_confirmed | Refund confirmed on-chain |
refund_failed | Refund failed (manual intervention required) |
no_refund_needed | No refund required (e.g., the target API ultimately charged during async processing) |
Where Statuses Appear
HTTPayer statuses may appear in:- JSON response bodies
- Webhook payloads
- Simulation endpoints (
/proxy/sim,/relay/sim) - Async job responses
For async flows and refunds, see the Webhooks documentation.