Java
الأخطاء وإعادة المحاولة
صنف استثناء لكل نوع من الرفض، وإعادة محاولات لا يمكن أن ترسل مرتين.
معالجة خطأ
try { client.templates().send("order-shipped", Body.of( "from", "[email protected]", "to", "[email protected]", "props", Body.of("orderId", "AC-4192") ));} catch (ValidationException error) { System.err.println(error.param() + " " + error.getMessage());} catch (RateLimitException error) { System.err.println("Wait " + error.retryAfterSeconds() + " seconds");} catch (ApiException error) { System.err.println(error.status() + " " + error.code() + " " + error.requestId());} catch (NetworkException error) { System.err.println(error.isTimeout() ? "Timed out" : "No response");}رفض الواجهة البرمجية يرمي ApiException، أو الصنف الفرعي الخاص بنوعه، مع ما قالته الواجهة البرمجية عنه. كل استثناء يرميه العميل هو OpenEmailException غير مُتحقَّق منه، لذا تكفي catch واحدة لالتقاطها كلها.
| الطريقة | ما يحتويه |
|---|---|
| status() | حالة HTTP، أو 0 حين لا تصل أي استجابة. |
| type(), code() | نوع الخطأ ورمزه في الواجهة البرمجية، مثل validation_error وinvalid_parameter. |
| param() | الحقل المسؤول عن الخطأ، إن وُجد. |
| requestId() | المعرّف الذي تذكره حين تراسل الدعم. |
| docUrl() | صفحة التوثيق التي تشرح الرمز. |
| retryAfterSeconds() | المدة التي طلبت منك الواجهة البرمجية انتظارها. |
| fields() | الحقول التي رفضها نموذج تسجيل، ولكل منها key وerror. |
| body() | جسم الاستجابة بعد فك ترميزه. |
أنواع الإخفاق
| الاستثناء | متى يُرمى |
|---|---|
| AuthenticationException | رُفض المفتاح أو الرمز، مع 401. |
| PermissionException | بيانات الاعتماد لا يُسمح لها بهذا، مع 403. |
| NotFoundException | لا شيء يحمل ذلك المعرّف، مع 404. |
| ConflictException | التغيير يتعارض مع الحالة الحالية، مع 409. |
| ValidationException | رُفض حقل، مع 422. |
| RateLimitException | طلبات كثيرة جدًا، أو استُنفدت حصة، مع 429. |
| InvalidRequestException | أي رفض آخر للطلب. |
| ApiException | فشلت الواجهة البرمجية، بحالة 500 أو أكثر. |
| NetworkException | لم تصل أي استجابة. |
| IllegalArgumentException | الاستدعاء نفسه كان خاطئًا، ولم يُرسل شيء. |
| WebhookSignatureException | تسليم ويب هوك لم يجتز فحصه. |
يجيب ApiException أيضًا عن أسئلة تخصه: isValidation() وisNotFound() وisRateLimited() وisServerError() وisRetryable()، ومعها isScopeMissing() حين ينقص بيانات الاعتماد النطاق الذي يحتاجه الاستدعاء وisStepUpRequired() حين يجب على رمز وصول أن يتحقق من رمز أولًا. وتخبرك NetworkException.isTimeout() بأن المهلة انقضت.
ما يُعاد تنفيذه
- عمليات القراءة والإرسال وكل كتابة يمكن تكرارها بأمان تُعاد محاولتها، حتى
maxRetriesمرة. وأي كتابة أخرى تُرسل مرة واحدة. - الحالات 408 و500 و502 و503 و504 تُعاد محاولتها مع انتظار يبدأ بنصف ثانية ويتضاعف حتى ثماني ثوانٍ.
- لا تُعاد محاولة 429 إلا حين يحمل
Retry-Afterبدقيقة أو أقل، وينتظر العميل تلك المدة. - الاتصال الذي يفشل أو تنتهي مهلته تُعاد محاولته بالطريقة نفسها.
الإرسال الذي تُعاد محاولته يحمل مفتاح عدم التكرار نفسه في كل مرة، فتعيد الواجهة البرمجية الرسالة الأولى بدل إرسال ثانية.