Rate limits and quotas

Requests are rate limited per key. When you go over, the API returns X0 — back off and retry.

Quotas#

Your quota is set by your plan and shown in your dashboard:

A search is one successful call to /search. Failed requests are not counted, and cached calls still return a result but are the cheapest way to stay under quota. Top-up searches are drawn down automatically once your monthly quota is used.

Handling 429#

When you exceed your limit, the API returns HTTP 429. Retry with exponential backoff rather than hammering the endpoint:

import time, requests

def search_with_retry(body, key, tries=4):
    for attempt in range(tries):
        r = requests.post(
            "https://api.oden-api.com/search",
            headers={"Authorization": f"Bearer {key}"},
            json=body, timeout=30,
        )
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        # Exponential backoff: 1s, 2s, 4s, 8s
        time.sleep(2 ** attempt)
    raise RuntimeError("ODEN rate limit: retries exhausted")

Staying under quota#

• Cache repeated queries on your side. Agents often re-ask the same thing; a local cache plus ODEN's own cached flag keeps spend down.
• Use depth: "basic" for cheap, snippet-level lookups where you do not need full extraction.
• Batch upstream, not at ODEN. There is no batch endpoint; if you have many queries, run them concurrently with a sensible pool size and backoff.

Next steps#

• See every status code: Errors.
• Compare plans: Pricing.