Response & Error Codes

Every successful v1.1 request returns 200 with the standard success envelope — including requests that match no data, which return 200 with an empty data array and a meta.emptyReason (see The Response Envelope). Every non-200 response returns one standard error envelope, so your error handling can be written once for the whole API.

The error envelope

{
  "error": {
    "status": 400,
    "code": "invalidDateRange",
    "message": "The 'from' date must be earlier than or equal to the 'to' date.",
    "details": [
      { "field": "from_date", "issue": "mustBeOnOrBeforeTo" }
    ],
    "request": {
      "namespace": "NASDAQ",
      "identifier": "NVDA",
      "from_date": "2026-02-15",
      "to_date": "2026-02-01"
    },
    "help": {
      "summary": "Correct the request parameters and retry.",
      "examples": [
        "/api/v11/stock/NASDAQ/NVDA/short/short_interest/?from_date=2026-02-01&to_date=2026-02-15"
      ],
      "url": null
    },
    "retryable": false,
    "requestId": null
  }
}

If you request CSV (?format=csv) and the request fails, the error is returned as a minimal two-column CSV (error_code,message) with the matching HTTP status.

Status codes and error codes

The code vocabulary is closed and stable — new codes are only added for genuinely new failure modes, and existing codes keep their meaning.

400 Bad Request — the request is malformed

Fix the parameter named in details and resend.

401 Unauthorized — no usable credential was presented

401 means we could not identify you: either no key was sent, or the key sent matches no account.

402 Payment Required — out of credits

The response tells you where the account stands, so one 402 is enough to decide what to do: wait for the renewal, top up, or fix a failed payment.

{
  "error": {
    "status": 402,
    "code": "creditsExhausted",
    "message": "Your Trader plan's 10,000 credits for the cycle ending 2026-11-10 are used up; they renew on 2026-11-10.",
    "details": null,
    "request": { "namespace": "NASDAQ", "identifier": "NVDA" },
    "context": {
      "plan": "Trader",
      "allowance": 10000,
      "used": 10000,
      "remaining": 0,
      "requestCost": 2.5,
      "cycleEndsAt": "2026-11-10T08:28:56+00:00",
      "renews": true,
      "subscriptionStatus": "active",
      "plansUrl": "https://app.ortex.com/apis/plans"
    },
    "help": {
      "summary": "Credits renew with your subscription cycle; to continue before then, top up or move to a larger plan.",
      "examples": [],
      "url": "https://app.ortex.com/apis/plans"
    },
    "retryable": false,
    "requestId": null
  }
}

Stop retrying on a 402. Nothing about the request changes the answer until the cycle renews or credits are added — and a client that keeps sending requests after a 402 is what the automatic block described under 403 apiKeyDenylisted below exists to catch. Check renews: if it is false, the credits will not come back on their own, so retrying at cycleEndsAt will fail too.

403 Forbidden — the key is known but not allowed

403 means we identified the key, but the request is refused. Either the key itself is no longer usable (expired, revoked, or its account disabled), or it is usable but not entitled to what was requested.

404 Not Found — the path or an identifier did not resolve

Note that a request that resolves correctly but matches no data is not a 404 — it is a 200 with meta.emptyReason (see The Response Envelope).

405 Method Not Allowed — wrong HTTP method for this route

409 Conflict — the request conflicts with the current state

The request was well-formed and authorized, but conflicts with what already exists (universe-maintainer endpoints, and bulk endpoints selecting one of your universes).

429 Too Many Requests — slow down

Use the Retry-After header rather than the retryable field to time your retry. A 429 carries Retry-After with the number of seconds to wait, plus RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset describing your allowance. Retry-After is a standard HTTP header, so most retry helpers act on it with no code from you:

# urllib3 / requests — honours Retry-After automatically
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry = Retry(total=5, backoff_factor=0.5, status_forcelist=[429, 503], respect_retry_after_header=True)
session.mount("https://", HTTPAdapter(max_retries=retry))

retryable in the body says whether a retry can succeed; Retry-After says when. Read both if you are handling retries yourself, and prefer the header if you are using a library.

500 Internal Server Error — our fault

Any other unexpected condition (for example, requesting CSV from a JSON-only endpoint, which yields 406 Not Acceptable) is wrapped in the same envelope with the generic code requestError.