दस्तऐवज

त्रुटी

प्रत्येक एंडपॉइंटवर प्रत्येक त्रुटी, एकाच JSON एनव्हलपचा वापर करते:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

code वर ब्रांच करा (स्थिर, मशीन-ओरिएंटेड); messageमाणसांना दाखवा. 429 प्रतिसादांमध्ये एक retry-after हेडर (सेकंदांमध्ये) देखील असतो.

सर्व एरर कोड

इन्फरन्स (chat & embeddings)

HTTP	Code	केव्हा	काय करावे
401	`invalid_api_key`	गहाळ, खराब, रद्द केलेली किंवा कालबाह्य झालेली key.	`Authorization: Bearer br-…` हेडर तपासा; dashboard वर एक नवीन key तयार करा.
404	`model_not_found`	Model id कॅटलॉगमध्ये नाही आणि BYOK-डिस्कव्हर्ड मॉडेलही नाही.	`GET /v1/models` वर वैध ids ची यादी पाहा; BYOK मॉडेलसाठी `provider/model-id` फॉर्मचा वापर करा.
400	`no_route`	मॉडेल अस्तित्वात आहे पण कोणताही रूट तुमच्या अटी पूर्ण करत नाही (सहसा `data_policy: india_only`, किंवा एक पिन केलेला provider जो डाउन/अनकॉन्फिगर्ड आहे).	अट सैल करा, कॅटलॉग मधून एक इंडिया-रेसिडेंट मॉडेल निवडा, किंवा आउटेज संपण्याची वाट पाहा (`GET /health`).
402	`insufficient_credits`	स्टँडर्ड key, बॅलन्स शून्य किंवा ऋण आहे.	टॉप अप करा. तसे करेपर्यंत पुन्हा प्रयत्न शक्य नाही.
429	`rate_limit_exceeded`	प्रति-मिनिट मर्यादा ओलांडली (key चा `rpm_limit` किंवा 120/min गेटवे कॅप).	`retry-after` नुसार मागे हटा; जर स्वतः-लावलेली असेल तर key ची मर्यादा वाढवा.
429	`daily_limit_reached`	Key ची दैनिक विनंती कॅप संपली.	मध्यरात्री IST ला रीसेट होते. कॅप वाढवा, किंवा ट्रायल key वरून अपग्रेड करा.
429	`budget_exceeded`	Key चे किंवा त्याच्या workspace चे मासिक ₹ बजेट संपले आहे.	dashboard वर बजेट वाढवा, किंवा नवीन महिन्याची (IST) वाट पाहा.
502	`all_routes_failed`	प्रत्येक पात्र रूटमध्ये त्रुटी आली; संदेशात शेवटची अपस्ट्रीम त्रुटी समाविष्ट आहे.	बॅकऑफसह पुन्हा प्रयत्न करा — सर्किट ~30 s मध्ये ठीक होतात. घटनांसाठी status तपासा.

Dashboard & account

HTTP	Code	केव्हा
401	`no_session`	साइन इन न करता एखाद्या `/me/*` एंडपॉइंटला कॉल करणे.
400	`duplicate_key_name`	त्या नावाची एक सक्रिय key तुमच्या org मध्ये आधीच अस्तित्वात आहे.
400	`trial_ceiling`	एका ट्रायल key ला 60 req/min किंवा 200 req/day च्या पुढे वाढवण्याचा प्रयत्न.
503	`provider_not_configured`	ती OAuth साइन-इन पद्धत या डिप्लॉयमेंटवर कॉन्फिगर केलेली नाही.

बिलिंग

HTTP	Code	केव्हा
400	`address_required`	बिलिंग पत्ता जोडण्यापूर्वी ऑर्डर तयार करणे.
400	`bad_address`	बिलिंग पत्ता पडताळणीत अयशस्वी झाला (संदेशात फील्डचे नाव सांगितले आहे).
400	`promo_invalid`	प्रोमो कोड अस्तित्वात नाही, कालबाह्य झाला आहे, किंवा संपला आहे.
400	`promo_redeemed`	तुमच्या org ने आधीच हा कोड वापरला आहे.
503	`billing_disabled`	या डिप्लॉयमेंटवर बिलिंग कॉन्फिगर केलेली नाही.

BYOK

HTTP	Code	केव्हा
400	`bad_key`	सबमिट केलेली key त्या provider साठी वैध दिसत नाही.
400	`unknown_provider`	असा कोणताही BYOK provider id नाही.
503	`byok_disabled`	या डिप्लॉयमेंटवर BYOK कॉन्फिगर केलेले नाही.

रूटिंग, collections, endpoints & teams

मॅनेजमेंट एंडपॉइंट्स पडताळणी कोडचा एक छोटा संच शेअर करतात:

HTTP	Code	केव्हा
403	`forbidden`	कृतीसाठी अशी भूमिका हवी जी तुमच्याकडे नाही (बहुतेक राइट्स फक्त owner/admin साठी आहेत).
404	`not_found`	तुमच्या org मध्ये असे कोणतेही collection, endpoint, chain, member किंवा invitation नाही.
400	`bad_steps` / `bad_model`	एखाद्या chain किंवा collection मध्ये अवैध steps आहेत, किंवा ते अशा मॉडेलला टार्गेट करते जे कॅटलॉग id नाही.
400	`bad_name` / `bad_readme`	नाव किंवा README पडताळणीत अयशस्वी ठरते (लांबी किंवा अक्षर).
400	`cap` / `team_cap` / `member_cap`	एक प्रति-org मर्यादा गाठली आहे (collections, team orgs, किंवा members).
400	`bad_request` / `unavailable`	BYOE कॉन्फिग अवैध आहे (उदा. SSRF-ब्लॉक केलेला URL) किंवा हे फीचर कॉन्फिगर केलेले नाही.
400	`bad_email` / `bad_role` / `already_member` / `already_invited` / `last_owner` / `personal_org`	सदस्यत्व त्रुटी — Teams पाहा (तुम्ही शेवटच्या owner ला पदावनत करू शकत नाही, किंवा एखाद्या personal org मध्ये members जोडू शकत नाही).
400	`duplicate_workspace`	त्या नावाचा एक workspace org मध्ये आधीच अस्तित्वात आहे.

कोडमध्ये त्रुटी हँडल करणे

OpenAI SDKs सोबत, BharatRouter त्रुटी SDK च्या मानक exceptions म्हणून समोर येतात — एनव्हलप त्याच्याच आत राहतो. एक रिट्राय पॉलिसी जी वरील प्रत्येक गोष्ट कव्हर करते:

# Python
import time, openai

def chat(client, **kw):
    for attempt in range(4):
        try:
            return client.chat.completions.create(**kw)
        except openai.RateLimitError as e:        # 429: rate/daily/budget
            code = (getattr(e, "body", None) or {}).get("error", {}).get("code")
            if code in ("daily_limit_reached", "budget_exceeded"):
                raise                              # waiting seconds won't help
            time.sleep(2 ** attempt)
        except openai.APIStatusError as e:
            if e.status_code == 502:               # all_routes_failed
                time.sleep(2 ** attempt)           # circuits recover in ~30s
            else:
                raise                              # 400/401/402: fix, don't retry
    raise RuntimeError("retries exhausted")

// Node
try {
  await client.chat.completions.create({ model: "gemma-4-e4b-it", messages });
} catch (err) {
  const code = err?.error?.code ?? err?.code;
  if (code === "insufficient_credits") notifyOwnerToTopUp();
  else if (err.status === 429) scheduleRetry(err.headers?.["retry-after"]);
  else if (err.status === 502) scheduleRetry(30);   // all_routes_failed
  else throw err;
}

ढोबळ नियम: 429 (daily_limit_reached /budget_exceeded वगळता) आणि 502 ला बॅकऑफसह रिट्राय करा; 400/401/402 ला कधीही डोळे झाकून रिट्राय करू नका — त्यांना संयमाची नाही, दुरुस्तीची गरज असते.