الأخطاء وحدود الاستخدام

ثلاثة أنواع من الفشل#

الفشل المتوقع قيمة لا استثناء#

كثير من العمليات تعيد اتحاداً من نوع نجاح ونوع خطأ أو أكثر بدل أن ترمي استثناءً. وطلب `__typename` والتفرّع عليه هو الطريقة المقصودة لاستخدامها — فطلب لا يستطيع الانتقال إلى الحالة التي طلبتها هو واقعة عن الطلب لا عطل.

mutation {
  transitionOrderToState(id: "1024", state: "Shipped") {
    __typename
    ... on Order { id state }
    ... on OrderStateTransitionError {
      errorCode        # e.g. ORDER_STATE_TRANSITION_ERROR
      message
      fromState
      toState
      transitionError
    }
  }
}

رفض الصلاحيات#

استدعاء عملية لم يُمنح مفتاحك صلاحيتها يعيد رمز 200 مع خطأ صلاحية في مصفوفة `errors`. ليس خللاً ولن تفيد إعادة المحاولة — على التاجر أن يصدر مفتاحاً بالصلاحية التي تحتاجها.

حدود الاستخدام#

تُحدّ حركة المفاتيح مرتين ضمن نافذة متحركة مدتها دقيقة: لكل مفتاح، ثم لكل مفتاح مع عنوان المصدر معاً. والسقف الأعلى هو سقف المفتاح، لذا فتوزيع المفتاح نفسه على عدة أجهزة لا يمنحك سعة أكبر.

تُحتسب طلبات POST الحاملة لمفتاح فقط. أما التاجر الذي يتصفح لوحته فيستوثق بجلسة لا بمفتاح، فلا يستهلك تصفّحه حصتك، ولا يستطيع تكاملك إبطاء لوحته.

التعامل مع 429#

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "errorCode": "RATE_LIMITED",
  "message": "Too many API requests — please retry shortly."
}

1. اقرأ Retry-After، وهو عدد الثواني حتى تُصفَّر النافذة.
2. انتظر هذه المدة على الأقل. فإعادة المحاولة فوراً تستهلك النافذة التالية أيضاً.
3. تراجع أسّياً إن تكرر الأمر، وأضف تشتيتاً عشوائياً — فعدة عمّال يعيدون المحاولة في اللحظة نفسها يعيدون إنتاج الاندفاع الذي تسبب بالحد.
4. عامل تكرار 429 المستمر كمشكلة تصميم لا كعارض: اجمع قراءاتك دفعةً واحدة، أو اشترك في الويب هوك بدل الاستجواب المتكرر.