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.

Order Rejections​

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

{
  "status": "REJECTED",
  "reason": "Insufficient margin: required=1500.00, available=1200.00"
}

reason is explanatory text, not a stable code. It can include live values and change as validation evolves. 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.

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