رموز خطأ واجهة برمجة التطبيقات وأفضل الممارسات

1) لماذا توحيد الأخطاء

القدرة على التنبؤ للعملاء: تنسيق واحد وسلوك retras.
Debug acceleration: 'trace _ id '/' request _ id', stable 'error _ code'.
الأمان: لن تتسرب آثار/تكوينات SQL/stack.
إمكانية الرصد: الإبلاغ عن تصنيف الأخطاء (التحقق من الصحة، والحصص، والمهل الزمنية، وما إلى ذلك).

2) المبادئ الأساسية

1. تنسيق استجابة واحد لجميع 4xx/5xx (و 2xx مع أخطاء جزئية - مخطط منفصل).
2. دلالات HTTP واضحة: الحالة الصحيحة هي الأكثر أهمية.
3. مستويين من الرموز: النقل («الحالة») والنطاق المستقر «الخطأ _ الرمز».
4. قابل للاسترجاع مقابل غير قابل للاسترداد: حدد صراحة وأعطي تلميحًا حول التراجع.
5. الضمان الافتراضي: التفاصيل - فقط للعميل صاحب الحقوق ؛ بدون آثار داخلية.
6. التوطين: يبقى رمز الآلة مستقرًا، النص - نترجم.

3) تنسيق خطأ واحد (استنادًا إلى RFC 7807)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

المطلوب: «نوع»، «عنوان»، «حالة»، «خطأ _ رمز»، «تتبع _ معرف».
اختياري: «أخطاء []» (حسب الحقول)، «قابلة للاسترجاع»، «تلميح»، «ميتا».

• «نوع المحتوى: التطبيق/المشكلة + json»
• "X-Request-ID "/" Traceparent' (W3C)
• (لـ 429/503) «إعادة المحاولة بعد» (ثوانٍ أو تاريخ)

4) دلالات أوضاع HTTP (دمج «الكلاسيكيات» والممارسة)

2xx (نجاح دقيق)

200 موافق نجاح شائع.
201 تم إنشاؤه - الموقع.
202 مقبول - بشكل غير متزامن في قائمة الانتظار (أعط «الحالة _ url»).
207 متعدد الأوضاع - نجاح جزئي (تجنب إن أمكن).

4xx (خطأ العميل)

400 طلب سيء - بناء/تنسيق، ولكن ليس التحقق الميداني (ويفضل 422).
401 غير مصرح به - لا/رمز غير صالح. دعونا «WWW-Authenticate».
403 ممنوع - الرمز المميز صحيح، ولكن لا توجد حقوق كافية (RBAC/ABAC/limits).
404 غير موجود - لا يوجد مورد/نقطة نهاية.
409 الصراع - القفل الأمثل، الغباء.
410 ذهب - تمت إزالة نقطة النهاية بشكل دائم.
412 فشل الشرط المسبق - فشل ETag/If-Match.
415 نوع الوسائط غير المدعومة - غير صالح «نوع المحتوى».
422 الكيان غير القابل للاختفاء - التحقق من قواعد الأعمال.
429 طلبات كثيرة جدا - تجاوزت الحصص/السرعة (انظر الفقرة 7).

5xx (خطأ في الخادم)

500 خطأ في الخادم الداخلي - خطأ مفاجئ ؛ عدم الكشف عن التفاصيل.
502 بوابة سيئة - خطأ المنبع.
503 خدمة غير متوفرة - التدهور/الحمل الزائد، أعط «Retry-After».
504 Gateway Timeout - المهلة الخلفية.

5) تصنيف المجال «خطأ _ كود»

• 'AUTH _' - التوثيق/الإذن.
• 'VAL _' - التحقق من صحة بيانات المدخلات.
• «RATELIMIT _» - الحصص والسرعة.
• 'IDEMP _' - idempotence/duplicates.
• «الصراع _» - الإصدارات/الحالة.
• 'DEP _' - التبعيات (PSP/DNS/SMTP).
• «ادفع _» - أخطاء تجارية في مجال الدفع.
• «SEC _» - الأمن (التوقيعات، HMAC، mTLS).
• «INT _» - مفاجئ داخلي.

• الاستقرار بمرور الوقت (المقارن الخلفي).
• الوصف والأمثلة في دليل الخطأ (مستندات + مقروءة آليا JSON).

6) قابل للاسترداد مقابل غير قابل للاسترداد

• "قابل للاسترداد:" أخطاء "حقيقية
• إذا كان «صحيح» - بالضرورة «Retry-After» (في ثوانٍ) أو عقد «التراجع الأسي (بدءًا من 1-2 ثانية، بحد أقصى 30-60 ثانية)».

قابل للاسترجاع عادة: «502/503/504»، حوالي «500»، «429» (بعد النافذة).
غير قابل للاسترجاع: '400/401/403/404/ 409/410/415/422'.

7) حد السعر وأخطاء الحصص (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• «إعادة المحاولة بعد: 12»
• "X-RateLimit-Limit' و" X-RateLimity-Resett' و "X-RateLimite-Resett'
• Для квот: «X-Cota-Limit' و» X-Cota-Remain «و» X-Conta-Resett'

8) الفراغ والصراعات

في طلبات الكتابة - «Idempotency-Key» (فريد في غضون 24-72 ساعة).
Retry conflict → 409 Conflict with 'error _ code: "IDEMP_REPLAY"'.
تعارض نسخة الموارد لـ ETag → 412 Precondition Failed.
في الرد، أرفق "المصدر _ المعرف "/" الحالة _ url' لإعادة الطلب الآمن.

9) التحقق و 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• لا تكرر نفس الشيء في 400-422 المفضل للتحقق من صحة الأعمال.
• والرسائل مقروءة من البشر ؛ «الرمز» يمكن قراءته آليًا.

10) خطأ أمني

أبدًا: آثار مكدسة، SQL، مسارات الملفات، أسماء المضيف الخاصة.
تحرير PII ؛ راقب اللائحة العامة لحماية البيانات/منطقة DSAR.
للتوقيع/HMAC، ميز بين 'SEC _ SIGNATURE _ MISMATCH' (403) و 'SEC _ TIMESTAMP _ SKEW' (401/403) مع «التحقق من الوقت ± 5 دقائق».

11) الارتباط وقابلية الملاحظة

أضف دائمًا «trace _ id »/« X-Request-ID» وقم بالتمرير عبر السجلات/المسارات.
أخطاء مجمعة عن طريق «خطأ _ رمز» و «حالة» → لوحات القيادة «أعلى الأخطاء»، «جديد مقابل معروف».
التنبيهات: 5xx/422/429 ارتفاع، زمن الوصول p95، حصة الأخطاء.

12) gRPC/GraphQL/Webhooks - خرائط

gRPC ↔ HTTP

الرسم البياني QL

النقل 200، ولكن "الأخطاء []" في الداخل - أضف "التوترات. الرمز 'и' trace _ id '.
بالنسبة إلى «القاتل» (المصادقة/الحصص) - فإن 401/403/429 HTTP الحقيقي أفضل.

شبكات الويب

ضع في اعتبارك أن المتلقين 2xx فقط ناجحون.
Retrai مع تراجع أسي، «X-Webhook-ID»، «X-Signature».
410 من المتلقي - توقف عن إعادة الدرج (تمت إزالة نقطة النهاية).

13) إصدار خطأ

«نوع »/« خطأ _ رمز» - مستقر ؛ جديد - أضف فقط.
عند تغيير مخطط الجسم، رفع النسخة الثانوية من API أو 'مشكلة + json ؛ v = 2 '.
الوثائق: جدول الرموز + أمثلة ؛ أخطاء التغيير.

14) التوثيق (شظايا OpenAPI)

الاستجابات العالمية

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

مثال على نقطة النهاية

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) الاختبار والجودة

عقد الاختبار: «طلب/مشكلة + جسون»، الحقول المطلوبة.
الاختبارات السلبية: جميع الفروع 401/403/404/ 409/422/429/500.
الفوضى/زمن الكمون: التحقق من عمليات إعادة التدوير لـ 5xx/ 503/504/429 («Retry-After»).
الاختبارات الأمنية: لا توجد رسائل داخلية، قناع PII صحيح.
المقارنة الخلفية: العملاء القدامى يفهمون مجالات جديدة (أضف، لا تنكسر).

16) قائمة التنفيذ المرجعية

• Single 'problem + json' + stable 'error _ code'.
• تصحيح دلالات HTTP/gRPC/GraphQL.
• التوصيات القابلة للاسترجاع/غير القابلة للاسترجاع + 'Retry-After '/التراجع.
• رؤوس حد السعر و 429 سلوكًا.
• Idempotency («Idempotency-Key»، 409/412).
• الأمن: لا توجد آثار/أسرار مكدسة، طبعة PII.
• 'التعقب _ id '/' X-Request-ID' في جميع الأخطاء.
• وثائق وأمثلة كتالوج الأخطاء.
• الرصد بتصنيف الخطأ.
• الاختبارات الذاتية للسيناريوهات السلبية.

17) الأسئلة الشائعة المصغرة

كيف يختلف 400 عن 422 ؟

400 - طلب مكسور (نوع التركيب/المحتوى). 422 - صالحة في الجملة، لكن قواعد العمل لم تمر.

متى 401 ومتى 403 ؟

401 - لا/رمز غير صحيح ؛ 403 - هناك رمز، لا توجد حقوق كافية.

هل هناك حاجة إلى «إعادة التجربة بعد» دائمًا ؟

مقابل 429/503، نعم ؛ بالنسبة للباقي، القابل للاسترجاع - من المستصوب تقديم توصية صريحة.

المجموع

الأخطاء المصممة جيدًا هي العقد: حالة HTTP الصحيحة، و «مشكلة + جسون» فردية، و «خطأ _ رمز» مستقر، وتلميحات إعادة طباعة صريحة، وأمان قوي. قم بتوحيد التنسيق، وتوثيق التصنيف، وإضافة القياس عن بعد والاختبارات - وتصبح واجهة برمجة التطبيقات الخاصة بك قابلة للتنبؤ وآمنة وصديقة للتكامل.