Errors & status codes

The error format, HTTP status codes, and common error responses for the Ornn Data API.

Error format

Errors return a JSON body with an error label and a human-readable message:

{
  "error": "Bad request",
  "message": "Invalid GPU type. Allowed: H100 SXM, H200, A100 SXM4, RTX 5090, B200, RTX PRO 6000 WS"
}

Status codes

Status	Meaning
200	Success.
400	Bad request: a missing or invalid parameter.
401	Unauthorized: missing, malformed, invalid, or revoked API key.
403	Forbidden: the request is authenticated but not allowed. A sk_prem_ key gets this on hourly, real-time, and neocloud routes. Creating a key can also 403 if the account cannot mint (no own grant and not a member of a Full organization).
404	Not found: no data for the requested parameters.
429	Too many requests. See Rate limits.
500	Internal server error.
503	Service unavailable (e.g. /health when the database is unreachable).

Common errors

401: Missing key

{
  "error": "Unauthorized",
  "message": "API key required. Use Authorization: Bearer YOUR_API_KEY"
}

401: Invalid or revoked key

{ "error": "Unauthorized", "message": "Invalid API key" }

{ "error": "Unauthorized", "message": "API key is inactive" }

403: Premium grain or dataset

A Premium (sk_prem_) key asking for a Full-only surface is refused rather than silently emptied:

{
  "error": "Forbidden",
  "message": "Premium access is daily-grain only. Hourly and real-time data require a full subscription."
}

{
  "error": "Forbidden",
  "message": "Neocloud site data is not included in premium access. A full subscription unlocks it."
}

See Access tiers.

403: Cannot mint a key

Trial, Premium, and Full own grants can mint keys. A member of a Full organization with no own grant can mint an unstamped sk_live_ key. A trial or Premium organization floor, with no own grant, cannot. POST /api/create-api-key then returns:

{ "success": false, "error": "API keys need an access grant of your own, or an organization on full access. Write to [e-mail] for an individual grant." }

See Manage API keys for details.

400: Unknown GPU

{
  "error": "Bad request",
  "message": "Invalid GPU type. Allowed: H100 SXM, H200, A100 SXM4, RTX 5090, B200, RTX PRO 6000 WS"
}

400: Missing required parameter

{
  "error": "Bad request",
  "message": "datetime query parameter is required (format: YYYY-MM-DD HH:MM:SS or ISO 8601)"
}

404: No data

{ "error": "No data available", "message": "No daily index data found for H100 SXM" }

Endpoints that return the nearest record, such as /api/gpu/{gpuName}/history, won’t 404 for an out-of-range timestamp. They return the closest match and report the gap in time_difference.

Handling errors

Always check the HTTP status before reading the body.

import requests

resp = requests.get(
    "https://api.ornnai.com/api/gpu/H100 SXM",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
if not resp.ok:
    err = resp.json()
    raise RuntimeError(f"{resp.status_code}: {err.get('message', err.get('error'))}")

data = resp.json()["data"]