enabled switches the rule on or off without touching its configuration. A field you leave out is left alone. Authenticate with an API key or a signed-in dashboard session. Costs no credits.
Route Metadata
| Field | Value |
|---|---|
| Method | PATCH |
| Path | /v1/webhooks/subscriptions/{id} |
| operationId | updateWebhookSubscription |
| Tag | Webhooks - Subscriptions |
| Family | Webhooks |
| Deprecated or legacy | no |
Human endpoint reference
OpenPATCH /v1/webhooks/subscriptions/{id} for authentication, parameters, responses, and examples.
Request Parameters
Path Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription path parameters",
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"description": "Subscription identifier.",
"type": "string",
"format": "uuid",
"example": "3c1f0a52-8d6b-4f0e-9b1a-6f2c4d8e9a10",
"x-parameter-location": "path"
}
}
}
Header Parameters
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription header parameters",
"type": "object",
"properties": {
"0xArchive-Version": {
"description": "Selects the 2026-10 response contract. Send `2026-10-01`; any dated version on or after it selects the same shapes. Without the header every response keeps its existing shape. With it:\n\n- The data quality routes, `/v1/status/coverage` and `/v1/symbols` answer the standard `{success, data, meta}` envelope.\n- Record times that are integer milliseconds by default become RFC 3339 UTC strings with millisecond precision, and the integer moves to a `*_ms` field: L4 resting-order `timestamp` (`timestamp_ms`), CVD buckets, HIP-3 oracle reads, Lighter and Lighter on Robinhood Chain liquidations and liquidation volume. Levels and trigger-levels `snapshot_ts` become RFC 3339 with `snapshot_ts_ms`.\n- Error bodies carry the contract `error_code` names: `invalid_parameter` instead of `invalid_query_params` and `invalid_path_params`, `historical_depth_exceeded` instead of `history_window_exceeded`, and `historical_range_exceeded` instead of `request_range_exceeded`; a malformed cursor that fails to parse answers 400 `invalid_cursor` instead of `invalid_query_params`. With `0xArchive-Version: 2026-10-01`, malformed cursors on trades, liquidations, L2 and L4 diffs, order history, TP/SL and order-flow routes answer 400 `invalid_cursor`. Without the header, the first six route families treat a malformed cursor as no cursor and return the first page; order flow answers 400 `invalid_query_params`. Malformed trade time inputs answer 400 `invalid_time_range` with the header and 400 `invalid_query_params` without it.\n\nThe response echoes the selected version in its own `0xArchive-Version` header.",
"type": "string",
"enum": [
"2026-10-01"
],
"example": "2026-10-01",
"x-parameter-location": "header"
}
}
}
Request Body
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription request body",
"description": "Edit a rule in place. Send `filters` (or its alias `config`), `enabled`, or both; a field you leave out is left alone, and other keys are ignored. A configuration is validated exactly as on create. Send `{}` as the configuration to clear it. Changing the configuration never requires deleting and recreating the rule.",
"type": "object",
"properties": {
"config": {
"description": "Alias of `filters`. Send one or the other.",
"allOf": [
{
"description": "What a subscription matches on. Every key is checked against the event type's catalog declaration, so an unknown key, an undeclared parameter or a condition on an undeclared metric is refused rather than ignored. The stored config is the normalised form: venues and addresses lowercased, declared parameters filled in at their defaults, and operators written in their canonical spelling.",
"type": "object",
"properties": {
"addresses": {
"description": "Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]
},
"conditions": {
"description": "Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.",
"type": "array",
"items": {
"description": "One condition on an event metric. The operator vocabulary is grouped by the metric's type; see `operators` on the event type.",
"type": "object",
"required": [
"metric",
"op"
],
"properties": {
"metric": {
"description": "A metric declared by the event type.",
"type": "string",
"example": "notional_usd"
},
"op": {
"description": "Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.",
"type": "string",
"enum": [
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal",
"equal",
"not_equal",
"between",
"not_between",
"in",
"not_in",
"contains",
"not_contains",
"starts_with",
"ends_with",
"before",
"after",
"is_empty",
"is_not_empty"
],
"example": "greater_than_or_equal"
},
"value": {
"description": "What to compare against. A number, string, boolean or RFC 3339 timestamp for a single value comparison; a two entry `[low, high]` list for `between` and `not_between`; a non-empty list for `in` and `not_in`. Omitted for `is_empty` and `is_not_empty`.",
"example": 100000
}
}
}
},
"min_notional_usd": {
"description": "Shorthand for a `notional_usd` at-or-above condition, kept for compatibility. It is stored as a condition, and it is mirrored back here as the loosest notional lower bound the config carries.",
"type": "number",
"example": 100000
},
"params": {
"description": "Parameter values for the event type, keyed by the parameter names it declares. A declared parameter you leave out is stored at its default. A declared parameter may also be written at the top level of the config.",
"type": "object",
"additionalProperties": true,
"example": {
"max_age_s": 3600
}
},
"symbols": {
"description": "Instrument symbols to match. Omit to match every symbol.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"BTC",
"ETH"
]
},
"venue": {
"description": "Venue or venues to match, from the event type's `venues` list. Accepts a single string, a pipe separated string or a list. Omit to match every covered venue.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"example": "hyperliquid"
}
}
}
]
},
"enabled": {
"description": "Your own on and off switch for the rule.",
"type": "boolean",
"example": true
},
"filters": {
"description": "New rule configuration.",
"allOf": [
{
"description": "What a subscription matches on. Every key is checked against the event type's catalog declaration, so an unknown key, an undeclared parameter or a condition on an undeclared metric is refused rather than ignored. The stored config is the normalised form: venues and addresses lowercased, declared parameters filled in at their defaults, and operators written in their canonical spelling.",
"type": "object",
"properties": {
"addresses": {
"description": "Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]
},
"conditions": {
"description": "Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.",
"type": "array",
"items": {
"description": "One condition on an event metric. The operator vocabulary is grouped by the metric's type; see `operators` on the event type.",
"type": "object",
"required": [
"metric",
"op"
],
"properties": {
"metric": {
"description": "A metric declared by the event type.",
"type": "string",
"example": "notional_usd"
},
"op": {
"description": "Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.",
"type": "string",
"enum": [
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal",
"equal",
"not_equal",
"between",
"not_between",
"in",
"not_in",
"contains",
"not_contains",
"starts_with",
"ends_with",
"before",
"after",
"is_empty",
"is_not_empty"
],
"example": "greater_than_or_equal"
},
"value": {
"description": "What to compare against. A number, string, boolean or RFC 3339 timestamp for a single value comparison; a two entry `[low, high]` list for `between` and `not_between`; a non-empty list for `in` and `not_in`. Omitted for `is_empty` and `is_not_empty`.",
"example": 100000
}
}
}
},
"min_notional_usd": {
"description": "Shorthand for a `notional_usd` at-or-above condition, kept for compatibility. It is stored as a condition, and it is mirrored back here as the loosest notional lower bound the config carries.",
"type": "number",
"example": 100000
},
"params": {
"description": "Parameter values for the event type, keyed by the parameter names it declares. A declared parameter you leave out is stored at its default. A declared parameter may also be written at the top level of the config.",
"type": "object",
"additionalProperties": true,
"example": {
"max_age_s": 3600
}
},
"symbols": {
"description": "Instrument symbols to match. Omit to match every symbol.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"BTC",
"ETH"
]
},
"venue": {
"description": "Venue or venues to match, from the event type's `venues` list. Accepts a single string, a pipe separated string or a list. Omit to match every covered venue.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"example": "hyperliquid"
}
}
}
]
}
}
}
Response Contracts
Status 200
The updated subscriptionapplication/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response 200",
"description": "API response containing one webhook subscription.",
"type": "object",
"properties": {
"data": {
"description": "A rule: one event type, one configuration, delivered to one endpoint.",
"type": "object",
"required": [
"created_at",
"enabled",
"endpoint_id",
"event_type",
"filters",
"id",
"last_suppressed_count",
"status",
"suppressed_count"
],
"properties": {
"created_at": {
"description": "When the rule was created.",
"type": "string",
"format": "date-time"
},
"enabled": {
"description": "Your own on and off switch. Resuming a paused rule never changes it.",
"type": "boolean",
"example": true
},
"endpoint_id": {
"description": "Endpoint that receives this rule's deliveries.",
"type": "string",
"format": "uuid"
},
"event_type": {
"description": "Event type this rule subscribes to.",
"type": "string",
"example": "market.liquidation"
},
"filters": {
"description": "What a subscription matches on. Every key is checked against the event type's catalog declaration, so an unknown key, an undeclared parameter or a condition on an undeclared metric is refused rather than ignored. The stored config is the normalised form: venues and addresses lowercased, declared parameters filled in at their defaults, and operators written in their canonical spelling.",
"type": "object",
"properties": {
"addresses": {
"description": "Wallets to match, for an address scoped event type. Every address must already be on your watched list. Omit to match all of them.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"0x6b9e773128f453f5c2c60935ee2de2cbc5390a24"
]
},
"conditions": {
"description": "Conditions on the event's metrics, all of which must hold for a delivery. At most 16 per subscription.",
"type": "array",
"items": {
"description": "One condition on an event metric. The operator vocabulary is grouped by the metric's type; see `operators` on the event type.",
"type": "object",
"required": [
"metric",
"op"
],
"properties": {
"metric": {
"description": "A metric declared by the event type.",
"type": "string",
"example": "notional_usd"
},
"op": {
"description": "Comparison to apply. Symbol spellings such as `>=` are accepted on the way in and stored in the canonical spelling shown here.",
"type": "string",
"enum": [
"greater_than",
"greater_than_or_equal",
"less_than",
"less_than_or_equal",
"equal",
"not_equal",
"between",
"not_between",
"in",
"not_in",
"contains",
"not_contains",
"starts_with",
"ends_with",
"before",
"after",
"is_empty",
"is_not_empty"
],
"example": "greater_than_or_equal"
},
"value": {
"description": "What to compare against. A number, string, boolean or RFC 3339 timestamp for a single value comparison; a two entry `[low, high]` list for `between` and `not_between`; a non-empty list for `in` and `not_in`. Omitted for `is_empty` and `is_not_empty`.",
"example": 100000
}
}
}
},
"min_notional_usd": {
"description": "Shorthand for a `notional_usd` at-or-above condition, kept for compatibility. It is stored as a condition, and it is mirrored back here as the loosest notional lower bound the config carries.",
"type": "number",
"example": 100000
},
"params": {
"description": "Parameter values for the event type, keyed by the parameter names it declares. A declared parameter you leave out is stored at its default. A declared parameter may also be written at the top level of the config.",
"type": "object",
"additionalProperties": true,
"example": {
"max_age_s": 3600
}
},
"symbols": {
"description": "Instrument symbols to match. Omit to match every symbol.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"BTC",
"ETH"
]
},
"venue": {
"description": "Venue or venues to match, from the event type's `venues` list. Accepts a single string, a pipe separated string or a list. Omit to match every covered venue.",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"example": "hyperliquid"
}
}
},
"id": {
"description": "Subscription identifier.",
"type": "string",
"format": "uuid"
},
"last_pause_reason": {
"description": "Cause of the last pause that has already ended, in the same vocabulary as `pause_reason`.",
"type": "string",
"nullable": true
},
"last_paused_at": {
"description": "Start of the last pause that has already ended.",
"type": "string",
"format": "date-time",
"nullable": true
},
"last_resumed_at": {
"description": "When that pause ended.",
"type": "string",
"format": "date-time",
"nullable": true
},
"last_suppressed_count": {
"description": "Matches suppressed during the last pause that has already ended.",
"type": "integer",
"format": "int64",
"example": 0
},
"last_suppressed_first_at": {
"description": "First suppressed match of that pause.",
"type": "string",
"format": "date-time",
"nullable": true
},
"last_suppressed_last_at": {
"description": "Most recent suppressed match of that pause.",
"type": "string",
"format": "date-time",
"nullable": true
},
"pause_message": {
"description": "Why this rule is paused and what clears it, in plain words. Present only while the rule is paused.",
"type": "string",
"example": "This rule was paused because the account reached its Pro plan limit of 50000 webhook deliveries in a day. The daily allowance resets at 2026-09-21 00:00 UTC, and a paused rule does not restart with it. Resume it with POST /v1/webhooks/subscriptions/resume."
},
"pause_reason": {
"description": "Machine readable cause of the current pause, either `deliveries_per_day_cap` (the account reached its daily delivery limit) or `plan_no_webhooks` (the plan does not include webhook delivery). Null while the rule is serving. Render `pause_message` for people.",
"type": "string",
"nullable": true,
"example": "deliveries_per_day_cap"
},
"paused_at": {
"description": "Start of the current gap. Null while the rule is serving.",
"type": "string",
"format": "date-time",
"nullable": true
},
"status": {
"description": "`active` is serving. `auto_paused` means delivery was paused for you and nothing is being sent; it stays paused until you resume it.",
"type": "string",
"enum": [
"active",
"auto_paused"
],
"example": "active"
},
"suppressed_count": {
"description": "Matches observed but not delivered since the current pause began. A lower bound, not a total: occurrences no active rule asked for are never looked at.",
"type": "integer",
"format": "int64",
"example": 0
},
"suppressed_first_at": {
"description": "First suppressed match of the current pause.",
"type": "string",
"format": "date-time",
"nullable": true
},
"suppressed_last_at": {
"description": "Most recent suppressed match of the current pause.",
"type": "string",
"format": "date-time",
"nullable": true
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
Status 400
Invalid request: a parameter, symbol, interval, cursor or time range failed validation. Seeerror_code.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response 400",
"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"
}
}
}
OpenAPI example: current_main
{
"code": 400,
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"error_code": "invalid_query_params",
"param": "limit",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"success": false
}
OpenAPI example: invalid_parameter
{
"success": false,
"code": 400,
"error_code": "invalid_parameter",
"error": "Invalid side 'up'. Use buy or sell.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"param": "side",
"valid_values": [
"buy",
"sell"
]
}
OpenAPI example: invalid_symbol
{
"success": false,
"code": 400,
"error_code": "invalid_symbol",
"error": "The symbol 'ZZZ' does not exist. Please see /v1/hyperliquid/instruments for available symbols.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"param": "symbol"
}
OpenAPI example: invalid_time_range
{
"success": false,
"code": 400,
"error_code": "invalid_time_range",
"error": "start must be <= end",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: legacy_invalid_query_params
{
"success": false,
"code": 400,
"error_code": "invalid_query_params",
"error": "Failed to deserialize query string: limit: invalid digit found in string",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status 401
Authentication required: the API key is missing or invalid.application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response 401",
"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"
}
}
}
OpenAPI example
{
"success": false,
"code": 401,
"error_code": "unauthorized",
"error": "Missing authentication credentials. Provide X-API-Key header or Bearer token.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status 404
Not found.not_found: the resource id is unknown. unsupported_for_venue: the venue does not offer this datatype (available_on names where it is served). route_not_found: no route matches the path.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response 404",
"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"
}
}
}
OpenAPI example: current_main
{
"code": 404,
"error": "No L4 checkpoint available before requested timestamp",
"error_code": "not_found",
"request_id": "ad7df471-eb8a-477c-bd9f-c685a9825f5b",
"success": false
}
OpenAPI example: not_found
{
"success": false,
"code": 404,
"error_code": "not_found",
"error": "Resource not found",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: route_not_found
{
"success": false,
"code": 404,
"error_code": "route_not_found",
"error": "No route matches GET /v1/not-a-route. GET /v1/capabilities lists the routes each venue serves.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: unsupported_for_venue
{
"success": false,
"code": 404,
"error_code": "unsupported_for_venue",
"error": "Order flow is not offered on Hyperliquid spot. It is available on Hyperliquid (/v1/hyperliquid/orders/{symbol}/flow), HIP-3 (/v1/hyperliquid/hip3/orders/{symbol}/flow) and HIP-4 (/v1/hyperliquid/hip4/orders/{symbol}/flow).",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"venue": "spot",
"datatype": "order_flow",
"available_on": [
{
"venue": "hyperliquid",
"route": "/v1/hyperliquid/orders/{symbol}/flow"
},
{
"venue": "hip3",
"route": "/v1/hyperliquid/hip3/orders/{symbol}/flow"
},
{
"venue": "hip4",
"route": "/v1/hyperliquid/hip4/orders/{symbol}/flow"
}
]
}
Status 429
Rate limit, concurrency limit or monthly credits exceeded. Seeerror_code.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response 429",
"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"
}
}
}
OpenAPI example: insufficient_credits
{
"success": false,
"code": 429,
"error_code": "insufficient_credits",
"error": "Monthly credit limit exceeded. Please upgrade your plan.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05",
"credits_used": 50000,
"credits_limit": 50000
}
OpenAPI example: rate_limited
{
"success": false,
"code": 429,
"error_code": "rate_limited",
"error": "Rate limit exceeded",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
Status default
Any other error. The body is anErrorResponse; branch on error_code. A 503 (upstream_unavailable) carries Retry-After.
application/json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "updateWebhookSubscription response default",
"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"
}
}
}
OpenAPI example: internal_error
{
"success": false,
"code": 500,
"error_code": "internal_error",
"error": "Internal server error",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}
OpenAPI example: upstream_unavailable
{
"success": false,
"code": 503,
"error_code": "upstream_unavailable",
"error": "The service is temporarily unavailable. Retry shortly.",
"request_id": "3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05"
}