Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt

Use this file to discover all available pages before exploring further.

Treat the HTTP status as the control signal and the JSON body as the debugging payload. Keep the request identifier from failed calls so the exact request can be found later.

​
Response Shape

Many application errors return the standard envelope: 
{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
Some auth, health, wallet, and data-quality responses use a resource-specific body instead. For example, an unauthenticated market-data request can return a compact JSON body with code and error plus an x-request-id header. Store that header when meta.request_id is not present.

​
Status Handling

StatusMeaningClient action
400Bad request, invalid parameter, unsupported symbol, or invalid time rangeFix the request before retrying
401Missing or invalid API keyCheck X-API-Key and key status
403Key does not have access to the route or access-gated dataChoose another route or update access
404Route, symbol, or resource not foundCheck venue namespace and symbol format
429Rate, concurrency, or credit limit reachedHonor Retry-After when present; otherwise use capped exponential backoff with jitter and reduce concurrency
5xxServer or upstream issueRetry with jitter, then check status/data quality

​
Error Handling Packet

Every client should keep enough context to decide whether the request should retry, stop, or route back to configuration.
FieldCapture
RequestMethod, full path, query parameters, venue family, and symbol
StatusHTTP status, error.code, and short message
Retry decisionRetry, back off, change input, change key, reduce concurrency, or stop
Request IDsFailed attempt IDs and final successful request ID, using meta.request_id, x-request-id, or the client wrapper’s request handle
TimingAttempt count, latency, backoff window, and data timestamp when the response includes one
Downstream effectWhether an output was skipped, delayed, marked incomplete, or safely continued
This packet belongs in application logs, job output, and support notes. It is also the minimum context a generated client or coding agent should expose when a call fails.

​
Retry Policy

Retry 429, transient 5xx, and network timeouts within a bounded budget. For 429, honor Retry-After when the response includes it; when it is absent, use capped exponential backoff with jitter and lower concurrency before widening the job again.

​
Next-Call Routing

Do not treat every failed request as a reason to rerun the same call faster. Route the next call by error class.
Error classNext call
Missing or invalid authStop the job, fix X-API-Key, then retry one small authenticated market-data route
Wrong venue or symbol familyCheck Venue Coverage and switch namespaces before retrying
rate_limited on high-volume raw eventsHonor Retry-After when present; otherwise use capped exponential backoff with jitter, reduce concurrency, and retry a smaller window
Repeated liquidation raw-event pressureUse /v1/hyperliquid/liquidations/{symbol}/volume or the matching HIP-3 /volume route when the workflow only needs aggregate liquidation-volume buckets
Malformed parameter or invalid time rangeFix the request shape before retrying; unchanged retries should stay blocked
The next-call packet should include the failed path, status, error.code, request ID, chosen retry delay, and the narrower route or namespace if the next attempt changes direction.

​
Request ID Discipline

Treat request IDs as part of your application log schema, not as optional debug detail. Store meta.request_id for successful market-data pulls, replay setup, failed attempts, and long-running scripts when an envelope exposes it. When a route returns a resource-specific body, such as auth failures or some data-quality endpoints, store the route path, parameters, returned status fields, and any request ID exposed by the response header or client wrapper. When a job spans pagination windows, keep the request ID per page instead of only storing the final one. For coding agents and generated clients, expose the request ID on the returned object or exception. A retry wrapper that hides the original response body makes production failures harder to diagnose. If the final retry succeeds, keep both the successful request ID and the failed attempt IDs in trace logs.

​
Support Context

When a failure needs help outside the client, include the packet above plus the account context and affected workflow. Do not include the API key. For data-quality issues, add the observed timestamp, expected freshness tolerance, and whether the affected route feeds a backtest, alert, dashboard, export, or model input.

​
Client Behavior By Class

Validation errors should fail fast. Auth errors should stop the job and point to the key source. Rate limits should honor Retry-After when present, otherwise back off with jitter, reduce concurrency, and preserve every request ID. Upstream or server errors can retry, but only within a bounded budget. Symbol and namespace errors should route back to Venue Coverage, because many apparent 404s are actually market-family mistakes.
Last modified on May 19, 2026