{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ErrorResponse",
"description": "Body of every non-2xx JSON response. `code` repeats the HTTP status, `error_code` is the stable machine-readable code (see `ErrorCode`), `error` is a human-readable message, and `request_id` identifies the request for support. Validation failures add `param` and, where the accepted set is fixed, `valid_values`. A 404 for a datatype the venue does not offer (`unsupported_for_venue`) adds `venue`, `datatype` and `available_on`; any other unknown path answers 404 `route_not_found`.",
"type": "object",
"required": [
"code",
"error",
"error_code",
"request_id",
"success"
],
"properties": {
"available_on": {
"description": "`unsupported_for_venue` only: the venues and routes that serve the datatype.",
"type": "array",
"items": {
"type": "object",
"required": [
"route",
"venue"
],
"properties": {
"route": {
"type": "string",
"example": "/v1/hyperliquid/orders/{symbol}/flow"
},
"venue": {
"type": "string",
"example": "hyperliquid"
}
}
}
},
"code": {
"description": "HTTP status code.",
"type": "integer",
"example": 400
},
"credits_limit": {
"description": "`insufficient_credits` only: the period's credit allowance.",
"type": "integer",
"format": "int64"
},
"credits_used": {
"description": "`insufficient_credits` only: credits used this period.",
"type": "integer",
"format": "int64"
},
"datatype": {
"description": "`unsupported_for_venue` only: the datatype the request asked for, as `GET /v1/capabilities` names it.",
"type": "string",
"example": "order_flow"
},
"error": {
"description": "Human-readable message. Wording can change; do not parse it.",
"type": "string"
},
"error_code": {
"description": "Stable, machine-readable error code. Branch on this value, not on the `error` text.\n\n**Contract codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_parameter` | 400 | A parameter failed to parse or validate. `param` names it and `valid_values` lists accepted values where the set is fixed. |\n| `invalid_symbol` | 400 | The symbol is not listed on this venue. |\n| `invalid_interval` | 400 | The `interval` (bucket width) is not one this route accepts. |\n| `invalid_cursor` | 400 | The `cursor` is malformed, stale, or was issued for other filters. Restart pagination without a cursor. Trades, liquidations, L2 and L4 diffs, order history and TP/SL routes currently return the first page for a malformed cursor instead. |\n| `invalid_time_range` | 400 | `start` is after `end`, or a time value could not be parsed. |\n| `range_before_coverage` | 400 | The whole requested range ends before the first instant this dataset is served from. |\n| `historical_range_exceeded` | 403 | The requested span is longer than the plan allows in one request or replay. |\n| `historical_depth_exceeded` | 403 | The request reaches further back than the plan's history window. |\n| `unsupported_for_venue` | 404 | The venue does not offer this datatype. The message, `datatype` and `available_on` name where it is served. |\n| `route_not_found` | 404 | No route matches the path or method. `GET /v1/capabilities` lists the routes each venue serves. |\n| `not_found` | 404 | The route exists but the requested resource (for example an incident, endpoint or outcome id) does not. |\n| `unauthorized` | 401 | The API key is missing or invalid. |\n| `forbidden` | 403 | The key is valid but not allowed to make this request. |\n| `insufficient_credits` | 429 | The monthly credit allowance is spent (402 on pay-per-request routes). |\n| `rate_limited` | 429 | Too many requests or concurrent queries. Retry after the interval in the rate-limit headers. |\n| `conflict` | 409 | The request conflicts with the current state of the resource. |\n| `upstream_unavailable` | 503 | A dependency is unavailable or saturated. Retry shortly; the response carries `Retry-After`. |\n| `internal_error` | 500 | An unexpected server error. Quote `request_id` when contacting support. |\n\n**WebSocket only** (sent in `{\"type\":\"error\"}` messages, never by REST)\n\n| Code | Where | Meaning |\n|---|---|---|\n| `endpoint_unsupported` | WebSocket | This WebSocket endpoint does not serve the channel or operation. The message names the endpoint that does. |\n| `slow_consumer` | WebSocket | The connection fell behind a stream and messages were dropped. Re-subscribe, or restart the replay, to resynchronise. |\n\n**Route-specific codes**\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `positions_unavailable` | 503 | Account positions are temporarily unavailable for this venue. |\n| `reconstruction_unavailable` | 503 | The as-of positions state for this instant cannot be reconstructed right now. |\n| `snapshot_advanced` | 409 | A positions market cursor pinned a snapshot that has since been replaced or expired. Restart pagination. |\n| `pagination_unavailable` | 503 | The next positions page cannot be served right now. Retry the same cursor shortly. |\n| `api_key_limit_reached` | 403 | The account already holds the maximum number of API keys for its plan. |\n| `wallet_requires_plan` | 402 | A wallet-authenticated key needs an active plan for this request. |\n| `wallet_account_required` | 403 | Wallet sign-in needs an existing account linked to the wallet. |\n| `wallet_free_signup_retired` | 410 | Free wallet sign-up is no longer offered. |\n| `account_disabled` | 403 | The account is disabled. |\n| `oauth_not_permitted` | 403 | This route is not available to OAuth access tokens. |\n| `insufficient_scope` | 403 | The OAuth access token lacks the scope this route requires. |\n\n**Legacy names.** Requests without `0xArchive-Version: 2026-10-01` keep the four names that predate the contract; with the header they receive the contract names instead.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_query_params` | 400 | Legacy name of `invalid_parameter` (query parameter), or of `invalid_cursor` when the parameter is `cursor`, sent without the version header. |\n| `invalid_path_params` | 400 | Legacy name of `invalid_parameter` (path parameter), sent without the version header. |\n| `history_window_exceeded` | 403 | Legacy name of `historical_depth_exceeded`, sent without the version header. |\n| `request_range_exceeded` | 403 | Legacy name of `historical_range_exceeded`, sent without the version header. |\n\nTreat any value not listed here as a generic error of the HTTP status.",
"type": "string",
"enum": [
"invalid_parameter",
"invalid_symbol",
"invalid_interval",
"invalid_cursor",
"invalid_time_range",
"range_before_coverage",
"historical_range_exceeded",
"historical_depth_exceeded",
"unsupported_for_venue",
"route_not_found",
"not_found",
"unauthorized",
"forbidden",
"insufficient_credits",
"rate_limited",
"conflict",
"upstream_unavailable",
"internal_error",
"endpoint_unsupported",
"slow_consumer",
"positions_unavailable",
"reconstruction_unavailable",
"snapshot_advanced",
"pagination_unavailable",
"api_key_limit_reached",
"wallet_requires_plan",
"wallet_account_required",
"wallet_free_signup_retired",
"account_disabled",
"oauth_not_permitted",
"insufficient_scope",
"invalid_query_params",
"invalid_path_params",
"history_window_exceeded",
"request_range_exceeded"
],
"example": "invalid_parameter"
},
"max_concurrent": {
"description": "`rate_limited` concurrency refusals only: simultaneous queries the plan allows.",
"type": "integer"
},
"param": {
"description": "The parameter that failed validation, when one did.",
"type": "string",
"example": "side"
},
"request_id": {
"description": "Unique request ID for support.",
"type": "string",
"format": "uuid"
},
"success": {
"description": "Always `false` on an error.",
"type": "boolean",
"enum": [
false
]
},
"suggestion": {
"description": "Present when the symbol exists on another venue: where to request it instead.",
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"example": "/v1/hyperliquid/hip3/trades/xyz:TSLA"
},
"symbol": {
"type": "string",
"example": "xyz:TSLA"
},
"venue": {
"type": "string",
"example": "hip3"
}
}
},
"valid_values": {
"description": "Accepted values of `param`, when the set is fixed.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"buy",
"sell"
]
},
"venue": {
"description": "`unsupported_for_venue` only: the venue the request asked.",
"type": "string",
"example": "spot"
}
}
}
