Errors

The API uses standard HTTP status codes. A non-2xx response means the call did not succeed; the body explains why.

Status codes#

Error response shape#

Errors return JSON with a message and, where available, the trace_id for the request:

{
  "error": "invalid_request",
  "message": "query must be 500 characters or fewer",
  "trace_id": "oden-mquycpae-p3thrk"
}

Handling errors well#

• Check the status code, not just the body. A 429 and a 400 need different responses — one retries, one is a bug in your request.
• Log the trace_id. It is the fastest way for us to find your request if you report an issue.
• Retry only what is retryable. 429 and 5xx are worth retrying with backoff; 400 and 401 are not — fix the request or the key.

r = requests.post(url, headers=headers, json=body, timeout=30)
if r.status_code == 401:
    raise RuntimeError("Check your ODEN_KEY")
if r.status_code == 400:
    raise ValueError(r.json().get("message", "bad request"))
if r.status_code in (429, 500, 502, 503):
    ...  # back off and retry
r.raise_for_status()
data = r.json()

Next steps#

• Rate limits — the detail behind 429.
• Authentication — the detail behind 401.