رموز معالجة الأخطاء والحالة

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

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

2) مبادئ التصميم

1. مخطط خطأ واحد لجميع الخدمات (REST/GraphQL/gRPC/webooks).
2. دلالات واضحة من retrays: التي ترمز إلى التراجع، والتي لا.
3. فشل مغلق في عمليات الكتابة: 4xx/5xx أفضل من عدم الاتساق الهادئ.
4. لا توجد تسريبات: لا تكشف عن SQL، الأكوام، التكوينات، المعرفات الداخلية.
5. Trace - Track 'trace _ id '/' correlation _ id'.
6. توطين الرسائل اختياري، لكن الرموز و «reason» تظل مستقرة.

3) تنسيق واحد (تفاصيل المشكلة/JSON)

json
{
"type": "https://errors.example.com/auth/invalid-token",
"title": "Invalid access token",
"status": 401,
"code": "AUTH_INVALID_TOKEN",
"detail": "Token expired or signature invalid.",
"instance": "/api/v1/payments/12345",
"trace_id": "01HX3...ABC",
"hint": "Obtain a new token via OAuth2 refresh.",
"meta": {
"scope": "payments:write",
"policy": "deny-by-default"
}
}

• 'نوع' هو مستقر فئة الخطأ URL.
• «رمز» - رمز آلة النطاق القصير (مستقر بين الإصدارات).
• «تلميح» - ماذا تفعل للعميل (تكرار، تحديث رمز، تغيير المعلمات).
• «meta» - أجزاء آمنة (بدون أسرار و PII).

4) خريطة رمز الحالة (المجموعة الدنيا)

التوثيق/الإذن

400 طلب سيء - التحقق الهيكلي/المخطط.
401 غير مصرح به - لا/رمز غير صالح. أضف «WWW-Authenticate».
403 ممنوع - موثق ولكن لا توجد حقوق/سياسات محرومة.
404 غير موجود - إخفاء وجود مورد بدون حقوق.
409 Conflict - version/state conflict (optional lock, idempotency).
451 غير متوفر لأسباب قانونية - الامتثال/حظر الولاية القضائية.

الحدود والحماية

408 طلب مهلة - يرسل العميل الجثة ببطء شديد.
409/425 مبكر جدا - حظر التكرار المبكر في 0-RTT/TLS 1. 3.
429 طلبات كثيرة جدًا - مع «إعادة التجربة بعد» وسياسة الحد.
499 طلب العميل المغلق - (في المحيط/NGINX) قام العميل بفصل الاتصال.

قواعد البيانات والأعمال

422 محتوى غير قابل للاختبار - تم تمرير التحقق من صحة العمل في المخطط، لكن المعنى غير صحيح.
423 مقفلة - محظورة الموارد (مراجعة KYC، تجميد AML).
409 Conflict - double submission, race, status reduction (see, «access process»).
410 ذهب - نقطة النهاية/الموارد محذوفة (استنكاف كامل).

خادم

500 خطأ في الخادم الداخلي - خطأ غير معروف ؛ لا تفصح عن التفاصيل.
502 Bad Gateway - التبعية عادت خطأ/وكيل.
503 خدمات غير متوفرة - التدهور/العمل المقرر ؛ أضف «إعادة المحاولة بعد».
504 بوابة تايم أوت.

5) دلالات إعادة الدرس والغباء

لا يمكنك التراجع عن 400/ 401/403/404/422 (ما لم يغير العميل الطلب).
يمكنك التراجع: 408/429/5xx/ 425/499/504 (مع backoff + jitter).
Idempotency: For 'POST', enable' Idempotency-Key '(UUIDv4).

لإعادة المحاولة، أعد 409 مع «تلميح:» استخدم نفس مفتاح الخصوصية أو وضع GET «».
أضف «Idempotency-Replay: true» عند إعادة نتيجة محفوظة.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1730641030

6) التحقق من صحة المدخلات: هيكل الخطأ الميداني

json
{
"type": "https://errors.example.com/validation",
"title": "Validation failed",
"status": 422,
"code": "VALIDATION_ERROR",
"trace_id": "01HX4...XYZ",
"errors": [
{"field": "amount", "rule": "min", "message": "Must be >= 10"},
{"field": "currency", "rule": "enum", "message": "Unsupported currency"}
]
}

7) فشل جزئي (فشل جزئي/دفعة)

json
{
"status": "partial",
"succeeded": 8,
"failed": 2,
"results": [
{"id": "op1", "status": 201},
{"id": "op2", "status": 422, "error": {"code":"VALIDATION_ERROR","detail":"..."}}
]
}

8) التثبيت والإجابات «الفارغة»

المجموعة الفارغة - بنود 200: []، وليس 404.
نهاية الصفحة - «الصفحة التالية _ الرمز المميز» مفقود.
رمز غير صحيح - رمز 400: PAGINATION_CURSOR_INVALID'.

9) خطوط الويب: تسليم موثوق

وقع الأحداث (HMAC) وتحقق قبل المعالجة.
الاستجابة للمعالجة الناجحة هي 2xx (أفضل 204).
أعطال المتلقي المؤقتة - 5xx ؛ المرسل يكرر (تراجع أسي، رعشة).
التفريغ بواسطة 'event _ id' وحفظ النتيجة (المستهلك المغرور).
حمولة غير صالحة - 400/422 بدون إعادة.

10) مطابقة البروتوكول (gRPC/GraphQL)

• «غير صالح _ حجة» 400 →
• 'غير مصرح به' → 401
• «إذن _ رفض» → 403
• «غير موجود» → 404
• «موجود بالفعل» → 409
• «شرط مسبق فاشل» → 412/422
• 'الموارد _ المستنفدة' → 429
• «أجهض» → 409
• 'غير متاح' → 503
• «الموعد النهائي _ تجاوز» → 504

json
{
"data": { "createPayment": null },
"errors": [{
"message": "Forbidden",
"extensions": { "code": "FORBIDDEN", "status": 403, "trace_id": "..." },
"path": ["createPayment"]
}]
}

يوصى باستخدام رمز HTTP المقابل بدلاً من 200 للأخطاء الحرجة.

11) العناوين ونصائح العملاء

«Retry-After» - ثانية/تاريخ HTTP (429/503/425/408).
«تحذير» - تدهور ناعم أو انتقاص («199 - الميزة X مكتئبة»).
'Deprecation', 'Sunset',' Link: <...>; rel = «الاستنكار» - للإغلاق الخاضع للرقابة.
«نوع المشكلة» (مخصص) - توجيه خطأ سريع على العميل.
'X-Trace-Id '/' Correlation-Id' - links logs/traces.

12) أمن الرسالة

لا تكرر أسرار الإدخال (الرموز/التوقيعات) في هيئة الاستجابة.
Mask PAN/PII ('1234').
مقابل 401/403 - لا تكشف عن السمة التي فشلت.
مقابل 404، بدلاً من «الموارد موجودة ولكن ليس لك» - 404 فقط.

13) إمكانية ملاحظة الأخطاء

• 'http _ أخطاء _ المجموع {الحالة، الطريق، المستأجر}'
• «خطأ _ فئات _ إجمالي {رمز}» (بواسطة «رمز» من الجسم)
• حصة 429، 5xx ؛ لوقت «p95 »/« p99» للإجابات الخاطئة بشكل منفصل
• 'retry _ after _ seconds _ bucket' - مخطط هسيمي لنصائح التكرار

• ربط الرد بـ "trace _ id" و "store" و "type" و "status' و" route "و" المستأجر "و" no PII ".

• ارتفاع معدل 5xx> X٪ في RPS> N ؛
• ونمو 429 على الطرق الحيوية ؛
• «مهلة/504» للتبعيات ؛
• 409/الخصوصية المتكررة → علامة على السباق.

14) أمثلة

14. 1 422 (التحقق من صحة الأعمال)

json
{
"type": "https://errors.example.com/payments/limit-exceeded",
"title": "Limit exceeded",
"status": 422,
"code": "PAYMENT_LIMIT_EXCEEDED",
"detail": "Daily withdrawal limit reached for KYC1.",
"hint": "Increase limits after KYC2 or try tomorrow.",
"trace_id": "01J5...XYZ"
}

14. 2 409 (الخصوصية)

HTTP/1.1 409 Conflict
Idempotency-Replay: true

json
{
"type": "https://errors.example.com/idempotency/replay",
"title": "Duplicate request",
"status": 409,
"code": "IDEMPOTENT_REPLAY",
"detail": "A request with the same Idempotency-Key was already processed.",
"hint": "Reuse the same Idempotency-Key and GET the operation status."
}

14. 3 429 (حدود)

json
{
"type":"https://errors.example.com/rate/too-many-requests",
"title":"Too many requests",
"status":429,
"code":"RATE_LIMITED",
"detail":"Per-key rate limit exceeded.",
"hint":"Retry after the time specified in Retry-After header."
}

15) أنتيباترن

إعادة 200 مع نص خطأ الجسم.
امزج تنسيقات خطأ مختلفة بين الخدمات.
توسيع المكدس/SQL/أسماء الجدول/عناوين URL الداخلية في «ذيل».
استخدم «رسالة» بدلاً من «رمز »/« نوع» مستقر.
العائد 500 عندما يحدث خطأ تجاري متوقع (على سبيل المثال، «الرصيد غير كاف»).
دلالات غير متسقة بين REST/GraphQL/gRPC.

16) تفاصيل iGaming/Finance

الرموز الواضحة لـ KYC/AML/العقوبات: 'KYC _ NEXT', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
القيود القضائية: 451 مع صياغة آمنة دون إدراج.
عمليات الكتابة النقدية: 409/423 للمنافسة والأقفال، «تلميح» مع نافذة إعادة.
ثوابت حد اللاعب: استخدم 422 لانتهاكات الدفع المسؤولة.
التدقيق: سجلات حلول غير قابلة للتغيير (رمز، وقت، ممثل، trace_id).

17) قائمة التحقق من الاستعداد

• مخطط خطأ JSON واحد، «نوع »/« رمز» مستقر.
• رسم خرائط HTTP ↔ gRPC/GraphQL متسق وموثق.
• إعادة الدلالات + «إعادة المحاولة بعد» ؛ الفراغ للكتابة.
• PII/القناع السري ؛ 404 لإخفاء الموارد.
• مقاييس الخطأ والإنذار ؛ الارتباط مع 'trace _ id'.
• استنكار السياسات: "Deprecation" و "Sunset' و" Link ".
• الاختبارات: سلبية/زغب، نسخة تضارب، انخفاض التبعية، تقديم مزدوج.
• دليل العملاء: أمثلة احتياطية ومعالجة 409/422/429/5xx.

18) TL ؛ د

قم بتوحيد تنسيق خطأ JSON واحد مع «نوع »/« رمز »/« تتبع _ id»، واستخدام رموز HTTP الصحيحة، والتمييز بين التحقق (400/422)، وحقوق (401/403/404)، والتضارب/الخصوصية (409)، والحدود (429). قم بإعطاء «Retry-After» و «تلميح» واضحين، وإخفاء البيانات الحساسة، وتسجيل الأخطاء مع «تتبع _ معرف» وبناء التنبيهات بحلول 5xx/429/p99.