Documentation ·وثائق
إرشادات تصميم الواجهات

الأخطاء

غلاف خطأ واحد برمز ورسالة ومعرّف طلب ورابط توثيق، ورموز الحالة المصاحبة له، وترويسات إعادة المحاولة.

اقرأ هذه الصفحة بـ English

في هذه الصفحة

نظرة سريعة#

تحمل استجابة الخطأ رمز الحالة الذي يصف ما حدث، وجسم JSON فيه كائن error واحد. الجسم نفسه لكل الواجهات، فيحلله العميل مرة واحدة.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your quota is exhausted. Retry after the time given in Retry-After, or upgrade your subscription.",
    "request_id": "3f6d0c1e-9a47-4b3f-8d0e-5a1c7b2e9f10",
    "docs_url": "https://api360.sa/docs/consumer/errors-and-retries#quota_exceeded"
  }
}
الحقلالنوعالمعنى
codestringرمز ثابت مقروء آلياً بصيغة snake_case. يتفرّع العميل بحسبه، لذلك لا يتغيّر معناه أبداً.
messagestringجملة للقارئ. تجيب الواجهة التي تخدم العربية والإنجليزية بلغة ترويسة Accept-Language. يمكن إعادة صياغة النص، أما code فلا.
request_idstringقيمة ترويسة الاستجابة X-Request-Id، فيشير أي بلاغ للدعم إلى استدعاء واحد.
docs_urlstringالصفحة التي تشرح الرمز.

الحقول code وmessage وrequest_id حاضرة دائماً. المزوّد الذي لا يستطيع ربط صفحة برمز ما يرسل مع ذلك docs_url بصفحة مرجع واجهته.

رموز الحالة#

الحالةمتى تُستخدمملاحظات
400الطلب مشوّه أو معامل خارج النطاقتشمل per_page الأكبر من الحد الأقصى
401بيانات الاعتماد غائبة أو غير صالحة
403المستدعي معروف وغير مسموح له
404العنصر أو المسار غير موجود
409الطلب يتعارض مع الحالة الحالية، أو Idempotency-Key ما زال قيد التنفيذ
422الطلب سليم الصيغة ولا يمكن معالجته، أو أُعيد استخدام Idempotency-Key مع طلب آخر
429استُنفدت حصة أو حد معدليرسل Retry-After وترويسات RateLimit-*
500 و502 و503 و504فشلت الخدمةيرسل 503 الترويسة Retry-After؛ ويعيد العميل المحاولة عند 502 و503 و504 مع تأخير متصاعد

استخدم الحالة المناسبة؛ ولا تُجب أبداً بـ 200 مع جسم خطأ.

الترويسات#

الترويسةعلىالقيمة
Retry-After429 و503عدد الثواني حتى تنجح إعادة المحاولة
RateLimit-Limit وRateLimit-Remaining وRateLimit-Resetالاستجابات التي تحمل حصة أو حد معدلالحد، وما تبقى منه، وثواني إعادة الضبط
X-Request-Idكل استجابةالقيمة نفسها في request_id
Content-Languageكل خطألغة message

في التعريف#

أعلن استجابات الخطأ التي قد تعيدها العملية، بمكوّن مشترك واحد، فيصف الملف الغلاف مرة واحدة:

components:
  responses:
    Error:
      description: The error envelope.
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: object
                required: [code, message, request_id]
                properties:
                  code: { type: string }
                  message: { type: string }
                  request_id: { type: string }
                  docs_url: { type: string }

تسرد كل عملية استجابة خطأ واحدة على الأقل (400 أو 401 أو 404 وهكذا، أو default) تشير إليه.

مخطّط له

تجيب البوابة عن كل خطأ تنتجه بنفسها، مثل مفتاح غائب أو مسار غير معروف أو حصة مستنفدة، بهذا الغلاف في كل البيئات، مع نشر رموز الأخطاء في فهرس واحد. أما الخطأ الذي تعيده خدمة المزوّد نفسها فيمرّ دون تغيير.

تتحقق منه#

القاعدةالشدةما تتحقق منه
api360-error-envelope-schemaerrorاستجابة 4xx أو 5xx أو default معلنة بجسم JSON تصف الغلاف: كائن error فيه code وmessage وrequest_id وdocs_url نصوصاً، والثلاثة الأولى مطلوبة
api360-error-responses-declaredwarnتعلن كل عملية استجابة خطأ واحدة على الأقل

انظر أيضاً#

هل كانت هذه الصفحة مفيدة؟
آخر تحديث 2026-10-17