Error Codes
HTTP status codes and error payloads across all oracle endpoints.
Standard HTTP Codes
| Status | Meaning | Action |
|---|---|---|
200 | Success — signed attestation returned | Verify signature, extract price from canonical |
402 | Payment Required | Parse payment instructions and pay (L402 invoice or x402 USDC) |
403 | Forbidden — address blocked | Payment address has been hard-blocked due to repeated failures |
404 | Not Found | Invalid endpoint path or DLC event ID not found |
425 | Too Early (DLC only) | Event announced but not yet attested — retry after maturity |
502 | Bad Gateway | Oracle backend unreachable or returned invalid data |
503 | Service Unavailable | Depeg circuit breaker active — USDC payments suspended |
x402 Error Payloads
| Status | Error Field | Description |
|---|---|---|
402 | X-PAYMENT header is required | No payment provided. Parse accepts array for payment requirements. |
402 | payment_verification_failed | Payment signature invalid, insufficient amount, or facilitator rejected. Check detail field. |
402 | invalid_x_payment_encoding | X-PAYMENT header is not valid base64 or not valid JSON. |
403 | payment_address_blocked | Wallet address hard-blocked. Includes tier and reason fields. |
502 | oracle_backend_error | Backend failed to respond within timeout. |
502 | backend_missing_canonical | Backend responded but without a canonical string. |
503 | depeg_circuit_breaker | USDC deviated beyond threshold. Includes usdc_rate and threshold. Use L402 as fallback. |
L402 Error Handling
The L402 proxy (Go) returns standard HTTP errors. The 402 response uses the WWW-Authenticate header rather than a JSON body. If the Lightning invoice has already been paid but the macaroon/preimage is invalid, you'll receive a 401 Unauthorized.
DLC Error Payloads
| Status | Detail | Meaning |
|---|---|---|
404 | Announcement not found: {eid} | No announcement exists for this event ID. |
404 | Event not found: {eid} | No announcement or attestation for this event ID. |
425 | Event announced but not yet attested. Maturity: {time} | Retry after the maturity timestamp. |
Timeout errors
If you get connection timeouts on cross-rate pairs (BTC/EUR, SOL/EUR, XAU/EUR, BTC/EUR VWAP), increase your HTTP client timeout to at least 15 seconds. These pairs fetch multiple component feeds and can take 6–7 seconds.