نظرة سريعة#
تحمل استجابة الخطأ رمز الحالة الذي يصف ما حدث، وجسم 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"
}
}| الحقل | النوع | المعنى |
|---|---|---|
code | string | رمز ثابت مقروء آلياً بصيغة snake_case. يتفرّع العميل بحسبه، لذلك لا يتغيّر معناه أبداً. |
message | string | جملة للقارئ. تجيب الواجهة التي تخدم العربية والإنجليزية بلغة ترويسة Accept-Language. يمكن إعادة صياغة النص، أما code فلا. |
request_id | string | قيمة ترويسة الاستجابة X-Request-Id، فيشير أي بلاغ للدعم إلى استدعاء واحد. |
docs_url | string | الصفحة التي تشرح الرمز. |
الحقول 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-After | 429 و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-schema | error | استجابة 4xx أو 5xx أو default معلنة بجسم JSON تصف الغلاف: كائن error فيه code وmessage وrequest_id وdocs_url نصوصاً، والثلاثة الأولى مطلوبة |
api360-error-responses-declared | warn | تعلن كل عملية استجابة خطأ واحدة على الأقل |
انظر أيضاً#
- الأخطاء ورموز الحالة وإعادة المحاولة: ما تجيب به البوابة اليوم.
- التكرار الآمن: الحالتان
409و422عند تكرار المفتاح. - الترقيم: الحالة
400عندper_pageالأكبر من الحد الأقصى.