Skip to main content

API Errors

Use the response surface that matches the request:

  • HTTP failure: a 4xx or 5xx JSON response has stable code and diagnostic message fields.
  • Order result: an HTTP 200 order response can still be rejected. Check its status and reason.
  • JSON-RPC response: JSON-RPC endpoints retain numeric error.code values inside an HTTP 200 response.

HTTP Error Responses​

Every API-generated HTTP 4xx and 5xx JSON error response includes:

{
  "error": "existing endpoint value, when present",
  "code": "invalid_field",
  "message": "price must be greater than zero"
}

code is the programmatic contract. Branch on this lowercase identifier and handle unknown future values safely. message is diagnostic text. Show or log it, but do not parse it.

error is a retained legacy field. Some endpoints already expose it and continue to do so, but it is opaque and not the new contract. Existing endpoint-specific fields, such as readiness details and Retry-After, remain present.

HEAD responses have no body. Use their HTTP status normally; Hypercall does not add a separate error-code header.

Withdrawal Preflight​

Core-delivery USDC withdrawals check recipient activation and transfer compatibility before accepting a new withdrawal. Handle withdrawal_destination_inactive and withdrawal_destination_mode_unsupported as destination errors. withdrawal_preflight_unavailable means verification is temporarily unavailable. withdrawal_source_unavailable requires the service to restore a compatible sending account or route.

These errors do not create a new withdrawal debit. A previously accepted request retains its existing status. Successful preflight does not guarantee delivery; continue monitoring the withdrawal's execution status. EVM-only withdrawals do not require HyperCore account eligibility.

Order Rejections​

An order can return HTTP 200 with a rejected execution result:

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, equity=1200.00, shortfall=300.00, current_consumed_initial_margin=900.00, incremental_order_initial_margin=600.00, current_consumed_maintenance_margin=500.00, incremental_order_maintenance_margin=250.00"
}

reason is explanatory text, not a stable code. It can include live values and change as validation evolves. For insufficient portfolio margin, required is the total post-order initial margin, while the current_consumed_* and incremental_order_* fields separate existing usage from the new order. Use status to identify a rejected order, then show or log reason. A stable order-rejection-code contract would be separate protocol and SDK work.

For Portfolio-margin perp orders, open_orders_initial_margin is the additional IM from the worst independently selectable unfilled or full-limit-fill state across live orders. An order can be accepted while the account is below IM only when adding it does not increase that envelope or the corresponding worst-fill maintenance capacity requirement. Open orders still do not change the published position MM. Clients must not infer that acceptance means the current account is fully funded, and must not parse the diagnostic reason to distinguish funded from non-worsening admission.

JSON-RPC Errors​

GET /orderbook retains its JSON-RPC-style response for a missing instrument:

{
  "jsonrpc": "2.0",
  "result": null,
  "error": {
    "code": 13020,
    "message": "not_found"
  }
}

Branch on the numeric error.code. RSM-specific JSON-RPC codes are not part of the default public HTTP catalog.

Public Error-Code Catalog​

This searchable catalog is generated from the info.x-hypercall-error-codes extension in the public OpenAPI document. It contains only consumer-facing HTTP and always-on JSON-RPC codes.

Loading API error catalog…

Handling Checklist​

  • HTTP clients: branch on code, preserve HTTP status, and honor Retry-After when present.
  • Order clients: treat status: "REJECTED" as an execution outcome even though the HTTP request succeeded.
  • JSON-RPC clients: branch on numeric error.code for the endpoint's native protocol.
  • All clients: keep a safe fallback for unknown future codes and never parse diagnostic messages.
Last updated on