इंस्टॉल नहीं होता या चलता नहीं तो क्या करें: शुरुआती समस्या निवारण
पहला रिक्वेस्ट नहीं चल रहा, तो आठ में से अधिकतर तीन जगह अटकता है: एनवायरनमेंट में गलत Python, Key ठीक से कॉन्फ़िगर नहीं, रिक्वेस्ट बॉडी नियमों के अनुरूप नहीं। यह पाठ सामान्य TypeSafe त्रुटियों को «त्रुटि के मूल पाठ» के अनुसार एक-एक करके कारण और समाधान देता है—पहले 60 सेकंड त्वरित जाँच, फिर सही स्थान पर मिलाएँ। सभी Python त्रुटियाँ typesafe-sdk v0.7.5, Python 3.12 पर वास्तव में पुनः उत्पन्न की गई हैं।
सीखने के बाद आप क्या कर सकते हैं
- 3 कमांड से 60 सेकंड में पता लगाएँ कि एनवायरनमेंट, Key, नेटवर्क में से कौन-सी कड़ी में समस्या है
- TypeSafe त्रुटियों को सही स्थान पर मिलाएँ: किस चरण में अटकी, क्या कारण, कैसे ठीक करें
- 7 HTTP स्टेटस कोड समझें (400/401/413/415/422/429/529) हर एक क्या कहता है
- कोड में
except TypeSafeAPIErrorसेstatusऔरrequest_idप्रिंट करें, प्रश्न पूछते समय सबूत साथ रखें - जानें कहाँ मदद लें: कंसोल, आधिकारिक दस्तावेज़, GitHub Issues, Discord
आपकी वर्तमान दुविधा
- pip से इंस्टॉल पूरा, चलाते ही
ModuleNotFoundError—इंस्टॉल नहीं हुआ, गलत Python उपयोग हुआ, या इसी नाम का गलत पैकेज इंस्टॉल हुआ? - Key स्पष्ट रूप से सेट किया, फिर भी 401, तीन बार दोबारा कॉपी किया
- त्रुटि संदेश JSON का ढेर है, समझ नहीं आता कौन-सा फ़ील्ड असली समस्या है
यह तरीका कब उपयोग करें
जब आपको चाहिए:
- पहला रिक्वेस्ट या वैकल्पिक इंस्टॉल तरीके में अटकी त्रुटियाँ ठीक करना
- अपना कोड लिखने से पहले जानना कि कहाँ गलती होने की संभावना है, गलती होने पर कौन-सा संकेत देखें
और आप नहीं चाहते:
- त्रुटि आते ही फ़ोरम पर पोस्ट करके जवाब का इंतज़ार, 60 सेकंड त्वरित जाँच अधिकांश इंतज़ार बचा सकती है
- «कोड गलत है» और «Key/कोटा/सर्वर की समस्या» में अंतर न कर पाना, आधे दिन बेकार कोड संशोधन
🎒 शुरू करने से पहले की तैयारी
- इंस्टॉल और पहला रिक्वेस्ट चला लिया हो (अटकना कोई बात नहीं, यही पाठ अटकाव हटाने के लिए है)
- टर्मिनल में Bash उपलब्ध हो (macOS / Linux / Windows WSL—आधिकारिक कमांड इसी एनवायरनमेंट के लिए लिखे गए हैं)
- एक ऐसा ब्राउज़र जिसमें TypeSafe कंसोल में लॉग इन हो (Key संबंधी समस्याओं में वापस देखना पड़ता है)
मूल विचार
पहले चरण पहचानें, फिर त्रुटि देखें। एक Jev कॉल चार चरणों से गुज़रती है, हर चरण की त्रुटियाँ अलग दिखती हैं:
| चरण | क्या जाँचें | विशिष्ट त्रुटियाँ |
|---|---|---|
| 1. एनवायरनमेंट | Python संस्करण, पैकेज सही इंस्टॉल हुआ या नहीं | ModuleNotFoundError |
| 2. प्रमाणीकरण | Key है भी या नहीं, सही है या नहीं | 401 / 403 (सीधे कनेक्ट पर प्रमाणीकरण हेडर नहीं गया, परीक्षित) / TypeSafeError (क्लाइंट बनाते ही थ्रो) |
| 3. रिक्वेस्ट बॉडी | JSON नियम, समस्या की परिभाषा | 400 / 422 |
| 4. सर्वर | रेट लिमिट, ओवरलोड | 429 / 529 |
SDK कुछ त्रुटियों को स्थानीय स्तर पर ही रोक देता है। v0.7.1 से, अमान्य Key पर क्लाइंट बनाते समय ही TypeSafeError थ्रो होता है, अनुरोध भेजा ही नहीं जाता; समस्या परिभाषा में criteria का अभाव भी स्थानीय स्तर पर रोका जाता है। इसलिए एक ही TypeSafeError होने पर भी, कुछ अनुरोध सर्वर तक पहुँचते ही नहीं — पहले "स्थानीय रोक" और "सर्वर से लौटी त्रुटि" में अंतर करें, दोनों का डिबगिंग दिशा बिल्कुल अलग है।
स्टेटस कोड की सूची। सर्वर से लौटी त्रुटियाँ मानक HTTP स्टेटस कोड लेकर आती हैं (docs/api/errors.md):
| स्टेटस कोड | अर्थ | एक लाइन में |
|---|---|---|
400 Bad Request | अनुरोध नियमों का उल्लंघन (UTF-8, नेस्टिंग की गहराई, गैर-परिमित संख्याएँ, खराब कंप्रेस्ड बॉडी); max_tokens_exceeded = संदर्भ सीमा से अधिक | अनुरोध बॉडी बदलें |
401 Unauthorized | Key अनुपस्थित या अमान्य | Key जाँचें |
413 Payload Too Large | अनुरोध बॉडी 32 MiB से बड़ी | आकार घटाएँ |
415 Unsupported Media Type | Content-Encoding असमर्थित या एक स्तर से अधिक कंप्रेशन | कंप्रेशन बदलें |
422 Unprocessable Entity | फ़ील्ड सत्यापन विफल, body फ़ील्ड बताता है | फ़ील्ड जोड़ें |
429 Too Many Requests | रेट लिमिट से अधिक | बैकऑफ़ के साथ पुनः प्रयास |
529 Overloaded | TypeSafe अस्थायी ओवरलोड | बैकऑफ़ के साथ पुनः प्रयास |
💡 प्रश्न पूछते समय request_id साथ रखें
SDK के API त्रुटि ऑब्जेक्ट में request_id होता है (x-typesafe-request-id रिस्पॉन्स हेडर से)। आधिकारिक फ़ीडबैक देते समय इसे साथ रखें, तो सामने वाला सीधे उस अनुरोध को खोज सकता है। Discord समुदाय का प्रवेश द्वार: discord.gg/typesafe।
पहली जाँच: 60 सेकंड में जाँच
तीन कमांड क्रम से चलाएँ — बारी-बारी से पैकेज, Key, और नेटवर्क व प्रमाणीकरण जाँचें; हर कमांड के साथ अपेक्षित आउटपुट दिया गया है।
# 1. 包装对了吗?——应该看到 0.7.5(或更高)
.venv/bin/python -c "import typesafe_sdk; print(typesafe_sdk.__version__)"
# 若报 ModuleNotFoundError:装的环境和跑的环境不是同一个,或装错了包(见下方排错)
# 2. Key 设置了吗?——应该看到完整 Key 字符串
echo "$TYPESAFE_API_KEY"
# 空的:export TYPESAFE_API_KEY="your-api-key" 再跑(新开终端要重新 export)
# 3. Key 真的有效吗?——应该看到 HTTP 401(说明网络通、你还没用真 Key)
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"
# 200 = 认证通过;401 = Key 无效(见下方排错)आपको यह दिखना चाहिए: पहली कमांड 1 वर्ज़न नंबर प्रिंट करे, दूसरी 2 Key प्रिंट करे, तीसरी 3 200 लौटाए (Key मान्य होने पर) या पहचानने योग्य स्टेटस कोड। जो कमांड विफल हो, वहीं से ठीक करें।
सामान्य समस्याओं की जाँच
परिवेश और इंस्टॉलेशन संबंधी समस्याएँ
"ModuleNotFoundError: No module named 'typesafe_sdk'"
कारण: पैकेज .venv में इंस्टॉल हुआ, लेकिन चलाने के लिए सिस्टम Python (या कोई और परिवेश) उपयोग हो रहा है — दोनों का इंटरप्रेटर एक ही नहीं है। दूसरी संभावना: pip install typesafe से उसी नाम का गलत पैकेज इंस्टॉल हो गया (अगला अनुभाग देखें)।
समाधान:
- हमेशा venv के इंटरप्रेटर से चलाएँ (आधिकारिक उदाहरण की शैली):
.venv/bin/python route_ticket.py- या पहले परिवेश सक्रिय करके चलाएँ (सामान्य venv उपयोग विधि):
source .venv/bin/activate
python route_ticket.py- फिर भी न चले तो पुष्टि करें कि पैकेज वाकई इंस्टॉल हुआ है:
.venv/bin/pip install typesafe-sdkदोबारा चलाएँ और आउटपुट मेंSuccessfully installedदेखें।
आपको यह दिखना चाहिए: तीन लाइनों का आउटपुट technical / 0.67 / 0.99 (मान वर्ज़न के साथ बदल सकते हैं, संरचना सही होनी चाहिए)।
"ImportError: cannot import name 'TypeSafeClient' from 'typesafe'"
कारण: pip install typesafe (-sdk छूट गया)** त्रुटि नहीं देता** — इससे उसी नाम का असंबंधित थर्ड-पार्टी लाइब्रेरी typesafe 0.9.1 ("formal type asserting decorators", लेखक Krister Hedfors, TypeSafe AI से कोई संबंध नहीं) इंस्टॉल होता है, जिसमें स्वाभाविक रूप से TypeSafeClient नहीं होता। इसलिए from typesafe import TypeSafeClient ImportError थ्रो करता है; उसी परिवेश में import typesafe_sdk ऊपर वाला ModuleNotFoundError थ्रो करता है।
समाधान:
- गलत पैकेज हटाकर सही पैकेज इंस्टॉल करें (इंस्टॉल नामहाइफ़न वाला
typesafe-sdkहै):
.venv/bin/pip uninstall -y typesafe
.venv/bin/pip install typesafe-sdk- import सत्यापित करें (import नामअंडरस्कोर वाला
typesafe_sdkहै):
.venv/bin/python -c "from typesafe_sdk import TypeSafeClient; print('ok')"आपको यह दिखना चाहिए: ok; pip आउटपुट में Successfully installed ... typesafe-sdk-0.7.5 शामिल हो।
Python वर्ज़न 3.10 से पुराना
कारण: आधिकारिक SDK को Python 3.10 या उससे नया चाहिए (docs/introduction/quickstart.md: "Requires Python 3.10 or later", PyPI मेटाडेटा requires-python = ">=3.10")।
समाधान:
- मौजूदा वर्ज़न देखें:
python3 --version- वर्ज़न 3.10 से पुराना है: 3.10+ इंस्टॉल करके उससे venv दोबारा बनाएँ (पुराना venv पुराने इंटरप्रेटर से बंधा है, दोबारा बनाना ज़रूरी है):
python3.10 -m venv .venv # 或你装好的更高版本
.venv/bin/pip install typesafe-sdkआपको यह दिखना चाहिए: .venv/bin/python --version Python 3.10 या उससे नया प्रिंट करे।
"zstd compression requires Python 3.14+ or the typesafe-sdk[zstd] extra."
कारण: आपने स्पष्ट रूप से compression='zstd' पास किया, लेकिन Python < 3.14 पर zstd समर्थन वैकल्पिक extra में होता है, जो डिफ़ॉल्ट इंस्टॉल में नहीं आता।
समाधान (दो विकल्प):
विकल्प 1 (extra इंस्टॉल करें, अनुशंसित):
.venv/bin/pip install "typesafe-sdk[zstd]"विकल्प 2 (कंप्रेशन बंद करें):
client = TypeSafeClient(compression=False)⚠️ v0.7.5 में डिफ़ॉल्ट रूप से कंप्रेशन चालू
v0.7.5 से SDK डिफ़ॉल्ट रूप से zstd कंप्रेशन का उपयोग करता है ≥1 KiB से बड़ी अनुरोध बॉडी के लिए (आधिकारिक changelog में नोट किया गया है: गैर-आधिकारिक API शायद तुरंत समर्थन न करें)। "zstd उपलब्ध सुनिश्चित करें" के लिए आधिकारिक कमांड uv add "typesafe-sdk[zstd]" है। वास्तविक परीक्षण में डिफ़ॉल्ट इंस्टॉल (extra के बिना) ऑब्जेक्ट बनाते समय त्रुटि नहीं देता — कंप्रेशन उपलब्ध हो तो उपयोग होता है, न हो तो कंप्रेशन नहीं होता; केवल स्पष्ट रूप से zstd माँगने पर यह त्रुटि थ्रो होती है।
"ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using pip install httpx[socks]."
कारण: परिवेश में SOCKS प्रॉक्स़ी कॉन्फ़िगर है (प्रॉक्स़ी परिवेश चर), SDK का HTTP लेयर (httpx2) SOCKS का उपयोग करने के लिए socksio पैकेज चाहिए, जो डिफ़ॉल्ट इंस्टॉल में नहीं आता — क्लाइंट बनाते समय ही यह त्रुटि थ्रो होती है, अनुरोध भेजा नहीं जा पाता।
समाधान: socksio इंस्टॉल करके क्लाइंट फिर से बनाएँ:
.venv/bin/pip install socksioआपको यह दिखना चाहिए: क्लाइंट सफलतापूर्वक बन गया (वास्तविक परीक्षण: socksio इंस्टॉल करने के बाद, उसी SOCKS प्रॉक्सी के साथ, क्लाइंट सामान्य रूप से बना)। एरर संदेश में सुझाया गया pip install httpx[socks] httpx परिवार का सामान्य संकेत है; SDK httpx2 का उपयोग करता है, सिर्फ socksio इंस्टॉल करना ही काफी है।
pip से इंस्टॉल नहीं हो रहा / पैकेज नहीं मिल रहा (नेटवर्क संबंधी)
कारण: आधिकारिक दस्तावेज़ TypeSafe के लिए कोई विशेष इंस्टॉलेशन-विफलता समाधान नहीं देते; आम स्थिति यह है कि PyPI स्रोत सर्वर तक नेटवर्क नहीं पहुँच रहा, या पैकेज का नाम गलत लिखने से कोई और पैकेज इंस्टॉल हो गया (ऊपर देखें)।
समाधान:
- पहले पैकेज-नाम की समस्या हटाएँ: सही कमांड है
pip install typesafe-sdk, सही इंस्टॉल होने पर आउटपुट मेंSuccessfully installed ... typesafe-sdk-0.7.5शामिल होता है। - नेटवर्क समस्याओं को अपने वातावरण के अनुसार संभालें (प्रॉक्सी और मिरर सोर्स सामान्य pip ज्ञान हैं, आधिकारिक दस्तावेज़ TypeSafe के लिए कोई विशेष समाधान नहीं देते)।
- Python < 3.10 होने पर pip इंस्टॉल सीधे मना कर सकता है (आधिकारिक न्यूनतम संस्करण 3.10), पहले पिछले चरण के अनुसार संस्करण ठीक करें।
प्रमाणीकरण और Key संबंधी समस्याएँ
"No API key was provided. Pass api_key or set the TYPESAFE_API_KEY environment variable."
कारण: न तो api_key पैरामीटर पास किया गया, न ही एनवायरनमेंट वेरिएबल सेट किया गया — SDK ने क्लाइंट बनाते समय ही रोक दिया। ध्यान दें: स्पष्ट रूप से खाली Key पास करने पर एनवायरनमेंट वेरिएबल पर वापस नहीं जाया जाता, api_key='' पास न करने के बराबर है।
समाधान:
- एनवायरनमेंट वेरिएबल विधि (आधिकारिक सिफारिश, कोड में Key न लिखें):
export TYPESAFE_API_KEY="your-api-key"- या कोड में स्पष्ट रूप से पैरामीटर पास करें:
from typesafe_sdk import TypeSafeClient
client = TypeSafeClient(api_key="your-api-key")आपको यह दिखना चाहिए: क्लाइंट सफलतापूर्वक बन गया, अब TypeSafeError नहीं फेंका जाता।
"Cannot authenticate with the server. Please check your API key and try again."
कारण: HTTP 401 — अनुरोध सर्वर तक पहुँचा, लेकिन Key अमान्य था। SDK TypeSafeAuthenticationError फेंकता है (str(e) का रूप POST https://api.typesafe.ai/v1/systemone: 401 Cannot authenticate... (request_id=req_...) जैसा होता है)।
समाधान:
- कंसोल के Keys पेज पर वापस जाकर Key एक बार फिर कॉपी करें (हाथ से लिखने पर गलती होने की संभावना रहती है)।
- फिर से सेट करें और सत्यापित करें:
export TYPESAFE_API_KEY="<重新复制的Key>"
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"आपको यह दिखना चाहिए: कमांड 200 और एक JSON लौटाती है ({"models":[...]}, जिसमें आपके खाते के उपलब्ध मॉडल और उपनाम सूचीबद्ध होते हैं)।
"Must supply an API key! Check your request and try again."
कारण: सीधे HTTP (curl / fetch) से कनेक्ट करते समय बिल्कुल नहीं जोड़ा गया Authorization हेडर — API ने सीधे मना कर दिया और 403 लौटाया (वास्तविक परीक्षण: बिना किसी प्रमाणीकरण हेडर के /v1/models का अनुरोध करने पर 403 और यह संदेश मिला; आधिकारिक स्टेटस कोड तालिका में 403 सूचीबद्ध नहीं है, SDK पक्ष पर संगत एक्सेप्शन क्लास TypeSafePermissionDeniedError है)। SDK उपयोगकर्ताओं को आम तौर पर यह नहीं मिलता: Key सही कॉन्फ़िगर होने पर SDK स्वतः हेडर जोड़ता है।
समाधान: Bearer प्रमाणीकरण हेडर जोड़कर भेजें:
curl --max-time 30 -s -w "\n%{http_code}\n" https://api.typesafe.ai/v1/models \
-H "Authorization: Bearer $TYPESAFE_API_KEY"आपको यह दिखना चाहिए: Key मान्य होने पर 200 और {"models":[...]} लौटता है; Key अमान्य होने पर यह 401 हो जाता है (पिछला चरण देखें)।
"API key must contain only printable ASCII characters without whitespace."
कारण: Key में भीतरी स्पेस, कंट्रोल कैरेक्टर या गैर-ASCII कैरेक्टर हैं (SDK केवलशुरुआत-अंत का व्हाइटस्पेस हटाता है, भीतर की समस्याजनक कैरेक्टर सीधे अस्वीकार कर दिए जाते हैं)।
समाधान: Key को पूरी तरह फिर से कॉपी करें, इसे जोड़ें नहीं, न ही हाथ से बदलें। पेस्ट करते समय ध्यान रखें कि बीच में कोई newline न घुसे।
अनुरोध बॉडी अस्वीकृत (400 / 413 / 415 / 422)
"422 Unprocessable Entity"
कारण: अनुरोध बॉडी के फ़ील्ड सत्यापन में विफलता — जैसे state अनुपस्थित, फ़ील्ड का फ़ॉर्मैट गलत। अनुरोध SDK के लोकल सत्यापन से गुज़रकर सर्वर तक पहुँचने के बाद, सर्वर 422 लौटाता है; रिस्पॉन्स बॉडी फ़ील्ड बताती है: loc स्थान है, msg कारण है (जैसे Field required)।
समाधान:
- कोड में
TypeSafeAPIErrorको कैच करें, पूरी बॉडी प्रिंट करके फ़ील्ड देखें (उदाहरण की समस्या मेंinstructionsशामिल है, जो लोकल सत्यापन पास करके वास्तव में सर्वर तक जाती है):
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print(error.status) # 服务器返回的状态码;422 = 字段校验失败
print(error.body) # 422 时里边 loc/msg 指明哪个字段
print(error.request_id) # 反馈给官方时带上locद्वारा बताए गए फ़ील्ड को पूरा करके फिर भेजें।
आपको यह दिखना चाहिए: अनुरोध वैध होने पर सामान्य रूप से परिणाम लौटता है; यदि सर्वर 422 लौटाता है, तो error.body में loc: ["body", "state"], msg: "Field required" जैसे फ़ील्ड-स्तरीय संकेत होते हैं (आधिकारिक OpenAPI उदाहरण)। सर्वर-साइड 422 का ठोस ट्रिगर रूप इस बात पर निर्भर करता है कि अनुरोध ने कौन-सा नियम तोड़ा है, बॉडी के वास्तविक रिस्पॉन्स को ही मान्य मानें।
::: टिप 💡 बहुत सारे 422 सर्वर तक पहुँचते ही नहीं Noul() बनाते समय instructions लिखना भूल गए तो SDK स्थानीय स्तर पर ही TypeSafeError: Noul question "q2" has neither instructions nor criteria; at least one is required. फेंक देगा; Score/Choice प्रश्न में criteria न होने पर भी स्थानीय स्तर पर रोका जाता है: TypeSafeError: Question "broken" requires "criteria". (broken की जगह आपकी अपनी प्रश्न की key का नाम होगा)। ये TypeSafeError बेस क्लास की एरर है, TypeSafeAPIError नहीं — बस कोड ठीक करें, नेटवर्क पर शक न करें। :::
"413 Payload Too Large"
कारण: अनुरोध बॉडी 32 MiB से बड़ी है (हेडर इसमें गिना नहीं जाता); कंप्रेस्ड और अनकंप्रेस्ट दोनों पर यही सीमा लागू होती है।
समाधान: state को छोटा करें, या बड़ी सामग्री को कई अनुरोधों में बाँटें।
"415 Unsupported Media Type"
कारण: Content-Encoding में असमर्थित एन्कोडिंग का उपयोग हुआ, या कंप्रेशन की एक से अधिक परतें लगी हैं (gzip / x-gzip / zstd प्रत्येक की केवल एक परत)।
समाधान: सीधे HTTP से कनेक्ट करते समय केवल एक परत कंप्रेशन का उपयोग करें; SDK उपयोगकर्ताओं को आम तौर पर यह नहीं मिलता (SDK स्वयं कंप्रेशन संभालता है)।
"max_tokens_exceeded"
कारण: अनुरोध मॉडल की संदर्भ (context) सीमा से बढ़ गया — 64k प्रति-अनुरोध (state + सभी प्रश्न) / 32k प्रति-प्रश्न (state + एक प्रश्न), दोनों में state शामिल है।
समाधान (तीन विकल्प, लागत कम से अधिक क्रम में):
विकल्प 1 (सामग्री छाँटें, अनुशंसित): state को फ़िल्टर करें और केवल उस प्रश्न के लिए आवश्यक फ़ील्ड भेजें — इससे पैसे भी बचते हैं और सटीकता भी बढ़ती है।
विकल्प 2 (लंबा संदर्भ): जिन अनुरोधों को चाहिए उनमें रिक्वेस्ट हेडर जोड़ें (दोनों संदर्भ 262k हो जाते हैं, यह अधिक धीमा और कम सटीक है, कीमत वही रहती है):
-H "TypeSafe-Danger-Zone-Long-Context: true"विकल्प 3 (प्रश्नों की संख्या घटाएँ या अनुरोध बाँटें): per-request सीमा में सभी प्रश्न शामिल होते हैं, प्रश्न बहुत अधिक हों तो पहले उन्हें बाँटें।
रेट लिमिट और सर्वर-साइड समस्याएँ
"429 Too Many Requests"
कारण: संगठन-स्तरीय रेट लिमिट पार हो गई (tokens/s + requests/s दोनों मीट्रिक, संगठन के अनुसार गिनी जाती है)।
समाधान:
- SDK का उपयोग करें (डिफ़ॉल्ट रूप से ही एक्सपोनेंशियल बैकऑफ़ रीट्राई के साथ आता है और
retry-afterका पालन करता है)——आपको कुछ भी करने की ज़रूरत नहीं है:
from typesafe_sdk import RetryPolicy, TypeSafeClient
# 默认就是自动重试;按需自定义(默认 max_retries=2、退避 0.5→5s、总预算 30s)
client = TypeSafeClient(retry=RetryPolicy(max_retries=3))- सीधे HTTP कनेक्ट करने पर ही आपको खुद एक्सपोनेंशियल बैकऑफ़ लिखना होगा, तुरंत वैसे ही दोबारा न भेजें।
- कोटा कंसोल के rate-limits पेज पर देखें; ज़्यादा चाहिए तो custom/enterprise लें (आवेदन फ़ॉर्म support.typesafe.ai/forms/rate-limit-increase-request)।
"529 Overloaded"
कारण: TypeSafe अस्थायी रूप से ओवरलोडेड है, 429 की तरह ही यह "थोड़ा रुककर दोबारा कोशिश करें" श्रेणी में आता है।
समाधान: वही जो 429——SDK अपने आप बैकऑफ़ के साथ रीट्राई करता है; सीधे कनेक्शन पर खुद बैकऑफ़ लिखें। लगातार आता रहे तो Discord या स्टेटस पेज देखें कि कहीं बड़े पैमाने पर खराबी तो नहीं है।
Agent Skill से जुड़ी समस्याएँ
"The agent isn't using the skill"
कारण: coding agent ने TypeSafe skill लोड नहीं की——नाम लेकर कॉल नहीं किया, गलत agent पर इंस्टॉल किया, या इंस्टॉल के बाद रीस्टार्ट नहीं किया।
समाधान (docs/agent-skill.md आधिकारिक 3 चरण):
- Claude Code प्लगइन में सीधे
/typesafe:typesafe-aiकॉल करें; अन्य agent में prompt में नाम लेकर"use the TypeSafe skill"कहें। - फिर भी न हो: पक्का करें कि इंस्टॉल के समय वही agent चुना था जिसे आप उपयोग कर रहे हैं (
npx skills addडिफ़ॉल्ट रूप से प्रोजेक्ट-स्तर पर इंस्टॉल करता है, ग्लोबल के लिए-gजोड़ें)। - Agent को रीस्टार्ट करके दोबारा कोशिश करें।
"The agent invents request or response fields"
कारण: skill का संस्करण पुराना है, वह उसे पुराना इंटरफ़ेस सिखा रही है।
समाधान: skill अपडेट करके दोबारा कोशिश करें (Claude Code):
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-aiफिर Claude Code रीस्टार्ट करें या /reload-plugins चलाएँ।
फिर भी नहीं होता?
पूछने से पहले सबूत जुटाएँ। एक न्यूनतम रिप्रोड्यूस करने योग्य कोड + त्रुटि का मूल पाठ + request_id, सौ वाक्यों के विवरण से ज़्यादा काम करता है:
# catch_report.py:复现问题并打印关键信息
from typesafe_sdk import Noul, TypeSafeClient, TypeSafeAPIError
with TypeSafeClient() as client:
try:
client.system_one("I was charged twice.", {
"billing": Noul(instructions="Is this about billing?")
})
except TypeSafeAPIError as error:
print("status:", error.status)
print("body:", error.body)
print("endpoint:", error.endpoint)
print("request_id:", error.request_id) # 提问必带
except Exception as error: # 本地拦截(Key/问题定义),没到服务器
print(type(error).__name__, str(error))और बारीक लॉग चाहिए तो SDK का लॉग स्तर ऊँचा कर दें (प्रमाणीकरण हेडर मास्क होंगे, लेकिन request/response बॉडी नहीं——संवेदनशील सामग्री सार्वजनिक जगह पर न भेजने का ध्यान रखें):
export TYPESAFE_LOG_LEVEL=debugकहाँ पूछें:
| चैनल | कब जाएँ |
|---|---|
| कंसोल Keys / rate-limits पेज | Key और कोटा जैसी समस्याएँ, पहले खुद जाँचें |
| आधिकारिक त्रुटि दस्तावेज़ | स्टेटस कोड के अर्थ और नियमों की बारीकियाँ |
| API क्विक रेफ़रेंस | यह साइट: request/response/स्टेटस कोड की त्वरित जाँच |
| GitHub Issues | SDK की खामियाँ (Python SDK रिपॉज़िटरी) |
| Discord समुदाय | आधिकारिक रूप से कहते हैं "Tell us what you build, and what breaks"——खराबी हो तो सीधे रिपोर्ट करें |
चेकपॉइंट ✅
- 60 सेकंड में जाँचने वाली तीनों कमांड मैं चला चुका हूँ, मुझे पता है कि किस चरण पर अटका है
- मैं स्थानीय रूप से रोके गए
TypeSafeError(Key, प्रश्न की परिभाषा) और सर्वर से लौटाए गएTypeSafeAPIErrorमें अंतर कर सकता हूँ - 401 होने पर मैं कंसोल पर जाकर Key दोबारा कॉपी करता हूँ, फिर curl
/v1/modelsसे सत्यापित करता हूँ - 429/529 मुझे पता है कि SDK डिफ़ॉल्ट रूप से अपने आप बैकऑफ़ रीट्राई करता है, खुद लिखने की ज़रूरत नहीं
- प्रश्न पूछते समय मैं न्यूनतम रिप्रोड्यूस कोड और
request_idसाथ देता हूँ
अक्सर पूछे जाने वाले प्रश्न
Jev की (API Key) कैसे सेट करें?
आधिकारिक तौर पर environment variable का उपयोग करने की सिफारिश की जाती है, कोड में Key न लिखें: export TYPESAFE_API_KEY="your-api-key", ध्यान दें कि नया terminal खोलने पर export दोबारा करना होगा। आप कोड में स्पष्ट रूप से parameter भी पास कर सकते हैं: TypeSafeClient(api_key="your-api-key")। ध्यान दें कि स्पष्ट रूप से खाली Key पास करने पर यह environment variable पर वापस नहीं जाएगा, api_key='' पास न करने के बराबर है — विवरण के लिए ऊपर देखें 「प्रमाणीकरण और Key संबंधी समस्याएँ」।
Key सेट करने के बाद भी 401 आता है तो क्या करें?
401 का अर्थ है कि अनुरोध सर्वर तक पहुँचा लेकिन Key अमान्य है। कंसोल Keys पेज पर वापस जाकर Key को पूरा दोबारा copy करें (हाथ से लिखने पर गलती होने की संभावना है, Key में internal space या non-ASCII characters नहीं होने चाहिए), दोबारा सेट करने के बाद curl से /v1/models अनुरोध करके जाँचें, 200 लौटने पर Key मान्य है।
TypeSafe AI की आधिकारिक documentation कहाँ है?
Status code के अर्थ और नियमों का विवरण आधिकारिक errors documentation docs.typesafe.ai/api/errors.md में देखें। Key और quota संबंधी समस्याओं के लिए पहले कंसोल पर जाँच करें, SDK की खामियों के लिए GitHub Issues में report करें, सेवा बंद होने पर सीधे Discord पर जाकर बताएँ।
पाठ का सारांश
✅ पहले चरण पहचानें: वातावरण (Python/पैकेज) → प्रमाणीकरण (Key) → request बॉडी (नियम) → सर्वर (रेट लिमिट/ओवरलोड)।
✅ मुख्य TypeSafe त्रुटियाँ सब हैंडल कर ली: ModuleNotFoundError सही इंटरप्रेटर चुनें, 401 Key दोबारा कॉपी करें, 422 loc फ़ील्ड देखें, 429/529 SDK के डिफ़ॉल्ट रीट्राई पर छोड़ दें।
✅ प्रश्न पूछने का तरीका: न्यूनतम रिप्रोड्यूस + त्रुटि का मूल पाठ + request_id, Discord या GitHub Issues पर जाएँ।
मुख्य तथ्यों की समीक्षा:
| संकेत | किस स्तर पर | पहला कदम |
|---|---|---|
ModuleNotFoundError | वातावरण | .venv/bin/python से चलाएँ |
ImportError: cannot import name 'TypeSafeClient' from 'typesafe' | वातावरण (गलत पैकेज इंस्टॉल) | typesafe हटाकर typesafe-sdk इंस्टॉल करें |
क्लाइंट बनाते समय TypeSafeError थ्रो होता है | प्रमाणीकरण (स्थानीय) | TYPESAFE_API_KEY जोड़ें |
401 + TypeSafeAuthenticationError | प्रमाणीकरण (सर्वर) | कंसोल पर जाकर Key दोबारा कॉपी करें |
422 | request बॉडी | बॉडी का loc/msg देखें |
429 / 529 | सर्वर | SDK के रीट्राई पर छोड़ें; सीधे कनेक्शन पर बैकऑफ़ लिखें |
अगले पाठ की झलक
शुरुआती परेशानी-निवारण यहीं पूरा——आपका वातावरण अब स्थिर है। अगला कदम रोज़मर्रा के उपयोग: Jev के पाँच तरीकों से प्रश्न पूछना सीखें।
आप सीखेंगे:
- State स्थिति: Jev को कैसा इनपुट दें
- Choice / Score / Noul तीनों प्रश्न-प्रकारों में से कौन-सा चुनें
- Confidence विश्वास स्तर का थ्रेशोल्ड से ब्रांचिंग कैसे करें
- request में इमेज कैसे भेजें