Skip to main content
Every Hyperoru endpoint returns a standard HTTP status code. Success always comes back as 2xx with a JSON body matching the documented schema. Failures are always a single JSON object with an error field and, usually, extra diagnostic context.

​
Error shape

{
  "error": "Account not found",
  "code": "ACCOUNT_NOT_FOUND",
  "request_id": "req_01J7..."
}
FieldMeaning
errorHuman-readable message. Safe to surface to end users.
codeMachine-readable code, stable across releases. Use this for branching logic.
request_idOpaque identifier for server-side tracing. Include it when contacting support.

​
Status codes

StatusMeaningTypical causeWhat to do
200 OKSuccessRequest completed, response body contains the resultNothing, proceed.
201 CreatedResource createdPOST that created a new trader, order, prompt, etc.Read the new resource’s id from the body.
202 AcceptedQueued for processingLong-running job accepted (e.g. backfills)Poll the job-status endpoint documented on the request.
204 No ContentSuccess, no bodyDelete or idempotent updateNothing, proceed.
400 Bad RequestInvalid inputMissing field, wrong type, or malformed JSONRead the error message, fix the request body, do not retry blindly.
401 UnauthorizedMissing or invalid tokenNo Authorization header, expired sessionLog in again, see Authentication.
403 ForbiddenToken valid, access deniedTrying to act on a resource you do not ownCheck the account or resource id in the URL.
404 Not FoundResource does not existWrong id, deleted resourceVerify the id; do not retry.
409 ConflictDuplicate or inconsistent stateCreating a resource that already exists, or updating one that has changedReconcile server state, retry with correct preconditions.
422 Unprocessable EntityBusiness-rule violationValid JSON shape, but violates a platform constraint (e.g. leverage too high)Read the error message and adjust. Do not retry blindly.
429 Too Many RequestsRate limitedExceeding request quotaBack off exponentially, see below.
500 Internal Server ErrorUnexpected server failureBug or transient upstream issueRetry with backoff. Contact support with request_id if persistent.
502 / 503 / 504Upstream or gateway failureDeployment in progress, exchange outageRetry with backoff. Check status.hyperoru.com.
Every endpoint page in this reference lists the exact error responses it can return. Expand the Responses section on any endpoint to see the full table.

​
Rate limits

Rate limits keep the platform responsive for everyone. They are applied per session token and per source IP, whichever is more restrictive.
CategoryLimit
Authentication (/api/users/login, /api/users/register)10 requests per minute per IP
Read-only endpoints (most GET)120 requests per minute per token
Mutating endpoints (POST, PUT, PATCH, DELETE)60 requests per minute per token
WebSocket messages240 messages per minute per connection
Market streams (GET /api/market-intelligence/stream, POST /api/hyper-ai/chat)1 concurrent stream per token
These are defaults. If your use case exceeds them legitimately, contact support@hyperoru.com to request an uplift.

​
Headers returned on every response

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1714000000
HeaderMeaning
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests you have left in the window
X-RateLimit-ResetUNIX timestamp (seconds) when the window resets

​
Handling 429 Too Many Requests

When you exceed a limit you receive: 
{
  "error": "Rate limit exceeded. Retry after 12 seconds.",
  "code": "RATE_LIMITED",
  "retry_after": 12
}
The retry_after field (and the Retry-After header) tells you the minimum number of seconds to wait.
Python
import time, requests

def call_with_backoff(url, headers, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.get(url, headers=headers)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)
    r.raise_for_status()

​
Retry strategy

1

Never retry 4xx other than 429

4xx errors (except 429) indicate a client bug. Retrying will not help and can lock out your account if you keep hammering the wrong credentials.
2

Retry 5xx and 429 with exponential backoff

Start at 1 second, double on each attempt, cap at 30 seconds, and add up to 500ms of jitter. Give up after 5-10 attempts.
3

Honor Retry-After when present

If the server gives you an explicit wait time, use it. Do not sleep less than that, even if your backoff schedule says so.
4

Log the request id

Capture request_id on every failure so support can trace it quickly. It is never sensitive.

​
Reporting an issue

When an error looks like a platform bug, email support@hyperoru.com with:
  • The request id (from X-Request-Id header or the error body).
  • The HTTP method and path you called.
  • The approximate timestamp (UTC) of the failure.
  • The response body you received.
Do not include your session token or passwords in a support email.

​
Next steps

Authentication

How to log in, rotate tokens, and keep them safe.

Trust and safety

How Hyperoru protects your keys, funds, and data.