Errors and request IDs

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.

Parameter Validation Errors

Parameters that fail to parse, such as text where a number belongs, return 400 with a compact JSON body: top-level code, error, error_code, and request_id. For query parameters the error string names the failing field and the exact parse failure; for path parameters it names the rejected value and the expected type. Either way the body points the fix at one parameter instead of the whole request. A malformed query parameter, such as ?limit=abc on a trades route, returns error_code invalid_query_params:

{
  "code": 400,
  "error": "Failed to deserialize query string: limit: invalid digit found in string",
  "error_code": "invalid_query_params",
  "request_id": "71acb440-10ba-4ebd-8e84-e253d6770b5a"
}

A malformed path parameter, such as a non-numeric ID on /v1/hyperliquid/hip4/outcomes/{outcome_id}, returns error_code invalid_path_params:

{
  "code": 400,
  "error": "Invalid URL: Cannot parse `notanumber` to a `u64`",
  "error_code": "invalid_path_params",
  "request_id": "83245f68-7429-4d14-bb50-2b16cab627a7"
}

Parameters that parse but carry an unsupported value, such as an unrecognized candle interval, return 400 with a field-specific body instead: param names the parameter, and where the accepted set is small the body lists it in valid_values. These value-level bodies do not carry error_code. Handle all of these the same way: fail fast, log request_id plus error_code or param, correct the parameter the body points to, and do not retry the request unchanged. Note that request_id sits at the top level of these bodies, not under meta.

Status Handling

Status	Meaning	Client action
`400`	Bad request, invalid parameter, unsupported symbol, or invalid time range	Fix the request before retrying; unparseable parameters carry `error_code` `invalid_query_params` or `invalid_path_params`, and unsupported values such as an unrecognized interval return a body with `param` naming the parameter
`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
Do not retry unchanged
Log

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.

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 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, because many apparent 404s are actually market-family mistakes.

Requests

Responses

Reliability

Errors and request IDs

Response Shape

Parameter Validation Errors

Status Handling

Error Handling Checklist

Retry Policy

Next-Call Routing

Request ID Discipline

Support Context

Client Behavior By Class

​Response Shape

​Parameter Validation Errors

​Status Handling

​Error Handling Checklist

​Retry Policy

​Next-Call Routing

​Request ID Discipline

​Support Context

​Client Behavior By Class

Response Shape

Parameter Validation Errors

Status Handling

Error Handling Checklist

Retry Policy

Next-Call Routing

Request ID Discipline

Support Context

Client Behavior By Class