Documentation Index
Fetch the complete documentation index at: https://docs.httpayer.com/llms.txt
Use this file to discover all available pages before exploring further.
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
HTTPayer uses two layers of status values. See the Status System reference for a full explanation of the mapping between them.
Sync-Response Statuses
These appear in the X-HTTPayer-Status response header and httpayerStatus field on synchronous responses. They are not stored in the webhooks database.
| Status | Description |
|---|
payment_required | Client must submit a valid x402 payment (402) |
payment_validating | On-chain confirmation in progress |
processing | Upstream API call in flight |
Async / Webhook Statuses
These are stored in the database and returned by GET /webhooks/:id. An initial async_processing record is created when background polling is launched (e.g., after a proxy 502 with webhook_id); it transitions to one of the terminal states below.
In-Flight
| Status | Webhook response | Description |
|---|
async_processing | pending | Background polling active; monitoring payment on-chain |
Terminal — Success
| Status | Webhook response | Description |
|---|
success | success | Request completed, upstream responded 2xx |
success_refunded | success_refunded | Request succeeded; refund issued (target did not charge) |
refund_confirmed | refund_confirmed | Refund transaction confirmed on-chain |
no_refund_needed | no_refund_needed | Target charged HTTPayer within the auth window — refund skipped |
Terminal — Failure
| Status | Webhook response | Description |
|---|
payment_failed | failed | User payment never settled on-chain |
upstream_error | failed | Target API returned a 5xx error |
internal_error | failed | HTTPayer-side error |
rate_limited | failed | Account daily_limit exceeded |
validation_failed | failed | Invalid request parameters |
refund_failed | failed | Refund attempt failed (manual intervention needed) |
Upstream Execution
Proxy: upstream payment refused (502)
When the target API returns 402 after all sync retries, HTTPayer returns 502 Bad Gateway with message: "Upstream API refused payment after N attempts". If blockchain polling is active, a webhook_id field is included in the response body — use GET /webhooks/:id to track whether the payment eventually confirmed on-chain. If confirmed, credits are charged; if not, reserved credits are automatically refunded.
SSRF protection (400)
The api_url field is validated before any outbound request is made. Requests targeting private, loopback, or link-local addresses are rejected with 400 Bad Request. Blocked ranges include:
- Loopback:
127.0.0.0/8, ::1
- Link-local / cloud metadata:
169.254.0.0/16
- Private:
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
- Unspecified:
0.0.0.0, ::
Non-http/https schemes (e.g. file://, ftp://) are also rejected.
Refund deduplication
If a refund has already been issued for a relay transaction (status confirmed or pending), any subsequent refund attempt for the same transaction is a no-op — the original refund hash is returned immediately without executing a new blockchain transaction. This prevents double-refunds from retries or concurrent error paths.
Where Statuses Appear
| Surface | Status type | Field / Header |
|---|
| Synchronous 2xx/4xx/5xx response | Sync-response status | X-HTTPayer-Status header |
| Synchronous JSON response body | Sync-response status | httpayerStatus field |
GET /webhooks/:id (202) | pending | status field |
GET /webhooks/:id (200) | success variant | status field |
GET /webhooks/:id (500) | failed | status field |
For async flows and refunds, see the Webhooks documentation.
