Guides / Production

Production · about 8 min

Handle errors, rate limits and retries

What each status means, which ones to retry, and a client that does it for you.

1. Know which errors to retry

   Status	Meaning	Do
   400 / 422	The request is malformed or invalid; detail lists every problem with its location	Fix the request; don't retry
   401	Missing or invalid key	Check JEV_API_KEY
   402	No balance left	Add credits (Settings → Billing)
   429	Rate limited	Wait Retry-After seconds, retry
   503	Temporarily unavailable	Retry with backoff

2. Retry with backoff

   import os, time, requests
   
   URL = "https://oramodel.com/v1/systemone"
   HEADERS = {"Authorization": f"Bearer {os.environ['JEV_API_KEY']}"}
   
   def decide(payload, attempts=4):
       for i in range(attempts):
           r = requests.post(URL, headers=HEADERS, json=payload, timeout=30)
           if r.status_code == 200:
               return r.json()
           if r.status_code in (429, 503) and i < attempts - 1:
               time.sleep(float(r.headers.get("Retry-After", 2 ** i)))
               continue
           raise RuntimeError(f"{r.status_code}: {r.json().get('detail')}")

3. Stay under your limits

   Limits are per organization (requests and input tokens per second), shared by all keys and the Playground. Every response carries x-ratelimit-limit-requests and x-ratelimit-limit-tokens. Put several questions in one request instead of one request per question.

4. Log what you need

   Log model (the exact version) and usage.input_tokens with each decision, so you can trace it and reconcile spend under Usage.

What's next

• Errors (reference)
• Rate limits