त्रुटियाँ
हर विफलता raise होती है। दो क्लास, और हर API त्रुटि पर एक request id।
इसे पकड़ना
from openemail import OpenEmailApiError, OpenEmailNetworkError, openemail try: openemail.emails.send({'from': sender, 'to': recipient, 'subject': subject, 'text': text})except OpenEmailApiError as error: if error.is_validation: print(error.code, error.param, error.message) if error.is_permission: print(openemail.addresses.list()) if error.is_rate_limited: print('try again in', error.retry_after_seconds, 'seconds') print(error.status, error.request_id) raiseexcept OpenEmailNetworkError as error: if error.is_timeout: print('no answer in time') raiseकिसी send पर आया permission_error आमतौर पर वर्कस्पेस का नहीं बल्कि KEY के send scope का मामला होता है (कोई डोमेन या पता जो उसे दिया ही नहीं गया); इसीलिए यह नमूना वह छापता है जो addresses.list() बताता है कि यह key किस रूप में भेज सकती है।
क्लास
| क्लास | कब |
|---|---|
| OpenEmailApiError | API ने उत्तर दिया, और सफलता के साथ नहीं। इसमें message, status, type, code, param, doc_url, request_id, retry_after_seconds, fields और body होते हैं। |
| OpenEmailNetworkError | कोई रिस्पॉन्स नहीं आया: DNS, TLS, टूटा हुआ कनेक्शन या timeout। इसमें cause होता है, यानी नीचे का httpx exception, और जब कारण timeout हो तो is_timeout True होता है। |
| OpenEmailError | दोनों का आधार, इसलिए एक ही except API या नेटवर्क से हुई हर विफलता पकड़ लेता है। WebhookVerificationError, जिसे verify_webhook_signature raise करता है, भी इसी से inherit करता है। |
| ValueError | कुछ भी भेजे जाने से पहले raise होती है: अनुपस्थित या खराब कुंजी, अनुपयोगी base_url, सादे http पर जाने वाला क्रेडेंशियल, खाली id। ग़लत http_client, या ऐसी body जिसे JSON नहीं ले जा सकता, इसकी जगह TypeError raise करती है। |
fields साइन-अप फ़ॉर्म द्वारा अस्वीकार किए गए हर उत्तर को key और error के रूप में सूचीबद्ध करता है, और बाकी हर त्रुटि पर None होता है। body वह JSON रखता है जो API ने भेजा, या None जब body JSON नहीं थी।
| प्रॉपर्टी | true कब |
|---|---|
| is_auth | type authentication_error है, यानी 401: कोई key नहीं, गलत किस्म का क्रेडेंशियल, या ऐसी key जो हमने जारी नहीं की। |
| is_permission | permission_error, यानी 403: असली key, पर उसके पास ज़रूरी scope या From पता नहीं। |
| is_scope_missing | code insufficient_scope है, वह 403 जो अनुपस्थित scope का नाम बताता है। |
| is_invalid_request | invalid_request_error, यानी 400: ऐसा अनुरोध जिसे समझा नहीं जा सका। आकार की सीमा से बड़ा संदेश 422 message_too_large बनकर लौटता है, इसलिए उसे पकड़ने वाली प्रॉपर्टी is_validation है। |
| is_validation | validation_error, यानी 422: schema ने इसे अस्वीकार किया, और param उस फ़ील्ड का नाम बताता है। |
| is_not_found | not_found_error, यानी 404: ऐसा कोई संसाधन नहीं। |
| is_conflict | conflict_error, यानी 409: संसाधन उस बिंदु से आगे निकल चुका है जहाँ उसके साथ यह किया जा सकता था। |
| is_rate_limited | rate_limit_error, यानी 429। जब सर्वर प्रतीक्षा बताता है तो वह retry_after_seconds में होती है। |
| is_server_error | status 500 या उससे ऊपर है। सपोर्ट से संपर्क करें तो request_id बताएँ। |
| is_retryable | status 408, 429, 500, 502, 503 या 504 है। |
| is_step_up_required | code का मान step_up_required है: वह 403 जो OAuth एक्सेस टोकन को संवेदनशील बदलाव से पहले मिलता है, जब तक व्यक्ति कोड सत्यापित न कर दे। |
ज़्यादातर प्रॉपर्टी type पढ़ती हैं, जो envelope का जमा हुआ आधा हिस्सा है। code str ही रहता है, क्योंकि API की गारंटी है कि वह खुला और जोड़ने योग्य है, इसलिए जिसे आप न पहचानें उसे उसके type की तरह बरतें। बंद Literal का मतलब होता कि नई विफलता पढ़ने की कीमत एक SDK अपग्रेड है।
जो body API का त्रुटि envelope नहीं है वह भी OpenEmailApiError ही बनती है, जिसमें type status से अनुमानित होता है और code unrecognised_response रखा जाता है। जिस सफल जवाब की body JSON नहीं है वह भी यही raise करता है।
AsyncOpenEmail कॉल को रद्द करने पर कोई OpenEmailError raise नहीं होती। रद्दीकरण ख़ुद ही आगे propagate होता है, चाहे वह अनुरोध के दौरान आए या retry से पहले की प्रतीक्षा के दौरान, और उसके बाद कुछ भी दोबारा नहीं आज़माया जाता।
request_id
हर OpenEmailApiError वह request id साथ रखती है जो सर्वर ने भेजी, error body से या x-request-id header से, और यही एकमात्र चीज़ है जो आपकी विफलता को सर्वर के लॉग की एक पंक्ति से जोड़ती है। सफल जवाब केवल पार्स की गई body लौटाता है, इसलिए उस पर पढ़ने को कोई request id नहीं होती।
str(error) के अंत में status, code और request id होते हैं, इसलिए exception छापने वाली लॉग पंक्ति तीनों को सहेज लेती है। OpenEmailApiError हर फ़ील्ड के साथ pickling में भी सुरक्षित रहती है, इसलिए किसी worker प्रोसेस में raise हुई त्रुटि parent प्रोसेस तक ज्यों की त्यों पहुँचती है।