> ## 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. # Errors and request IDs > Handle 0xArchive HTTP errors, JSON error bodies, retries, request identifiers, and response metadata when integrating clients. 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: ```json theme={"theme":"github-dark"} { "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 | Status | Meaning | Client action | | ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `400` | Bad request, invalid parameter, unsupported symbol, or invalid time range | Fix the request before retrying | | `401` | Missing or invalid API key | Check `X-API-Key` and key status | | `403` | Key does not have access to the route or access-gated data | Choose another route or update access | | `404` | Route, symbol, or resource not found | Check venue namespace and symbol format | | `429` | Rate, concurrency, or credit limit reached | Honor `Retry-After` when present; otherwise use capped exponential backoff with jitter and reduce concurrency | | `5xx` | Server or upstream issue | Retry with jitter, then check status/data quality | ## Error Handling Checklist Every client should keep enough context to decide whether the request should retry, stop, or route back to configuration. | Field | Capture | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Request | Method, full path, query parameters, venue family, and symbol | | Status | HTTP status, `error.code`, and short message | | Retry decision | Retry, back off, change input, change key, reduce concurrency, or stop | | Request IDs | Failed attempt IDs and final successful request ID, using `meta.request_id`, `x-request-id`, or the client wrapper's request handle | | Timing | Attempt count, latency, backoff window, and data timestamp when the response includes one | | Downstream effect | Whether an output was skipped, delayed, marked incomplete, or safely continued | This checklist 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. Do not retry malformed requests, invalid symbols, missing auth, access-gated routes, or unsupported parameters without changing the request or key. Log method, path, venue family, symbol, status, error code, attempt number, backoff delay, and the request identifier from `meta.request_id`, `x-request-id`, or the client wrapper. ## 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 class | Next call | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Missing or invalid auth | Stop the job, fix `X-API-Key`, then retry one small authenticated market-data route | | Wrong venue or symbol family | Check [Venue coverage](/venue-coverage) and switch namespaces before retrying | | `rate_limited` on high-volume raw events | Honor `Retry-After` when present; otherwise use capped exponential backoff with jitter, reduce concurrency, and retry a smaller window | | Repeated liquidation raw-event pressure | Use `/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 range | Fix the request shape before retrying; unchanged retries should stay blocked | The next-call checklist 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 checklist 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](/venue-coverage), because many apparent 404s are actually market-family mistakes.