مدیریت خطا و کدهای وضعیت

1) چرا استاندارد کردن خطاها

• قابل پیش بینی نوع مشکل را رمزگذاری می کند،
• به مشتری پیشنهادات معتبر می دهد (چه کاری باید انجام شود)،
• محافظت در برابر نشت قطعات داخلی،
• سازگار با retras و idemotency.

2) اصول طراحی

1. یک طرح خطا برای تمام خدمات (REST/GraphQL/gRPC/webhooks).
2. معنایی روشن از retrays: که کدهای به retract، که نه.
3. Fail-closed در عملیات نوشتن: 4xx/5xx بهتر از ناسازگاری آرام است.
4. بدون نشت: SQL، پشته ها، پیکربندی ها، شناسه های داخلی را فاش نکنید.
5. Trace - همیشه «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"
}
}

• «type» یک URL کلاس خطای پایدار است.
• 'code' - کد ماشین دامنه کوتاه (پایدار بین نسخه ها).
• 'hint' - چه کاری برای مشتری انجام دهید (تکرار، به روز رسانی نشانه، تغییر پارامترها).
• «meta» - قطعات امن (بدون اسرار و PII).

4) نقشه کد وضعیت (حداقل مجموعه)

احراز هویت/مجوز

400 Bad Request - اعتبارسنجی ساختاری/طرح.
401 توکن غیر مجاز - بدون/نامعتبر. «WWW-Authenticate» را اضافه کنید.
۴۰۳ ممنوع - تصدیق شده اما هیچ حقوق/سیاستی رد نشده است.
۴۰۴ Not Found - وجود یک منبع بدون حقوق را پنهان می کند.
۴۰۹ Conflict - version/state conflict (قفل خوش بینانه، idempotency).
451 به دلایل قانونی در دسترس نیست - بلوک انطباق/صلاحیت.

محدودیت ها و حفاظت

۴۰۸ Request Timeout - مشتری بدن را خیلی آهسته ارسال می کند.
۴۰۹/۴۲۵ خیلی زود - ممنوعیت تکرار زودهنگام در 0-RTT/TLS ۱. 3.
۴۲۹ Too many requests - with «Retry-After» و سیاست محدود کردن.
499 Closed Request - (در محیط/NGINX) مشتری اتصال را قطع کرد.

داده ها و قوانین کسب و کار

422 محتوای غیر قابل پردازش - اعتبار سنجی کسب و کار این طرح را تصویب کرد، اما معنی نادرست است.
423 Locked - resource blocked (بررسی KYC، مسدود کردن AML).
409 تعارض - تسلیم دوگانه، نژاد، محدودیت وضعیت (به عنوان مثال، «در حال حاضر در حال پردازش»).
۴۱۰ Gone - endpoint/resource حذف شده است.

سرور مجازی

500 خطای سرور داخلی - خطای ناشناخته ؛ جزئیات را فاش نکنید.
502 Bad Gateway - خطای بازگشت وابستگی/پراکسی.
503 سرویس در دسترس نیست - تخریب/کار برنامه ریزی شده ؛ اضافه کردن 'retry-after'.
504 اتمام وقت دروازه.

قانون: عملیات را روی شک و تردید بنویسید → 409 (درگیری) یا 503 (بعداً تکرار کنید)، نه 200.

5) معناشناسی Retray و idempotency

شما نمی توانید 400/ 401/403/404/422 را رد کنید (مگر اینکه مشتری درخواست را تغییر داده باشد).
شما می توانید retract: 408/429/5xx/ 425/499/504 (با عقب نشینی + لرزش).
Idempotency: برای «POST»، «Idempotency-Key» (UUIDv4) را فعال کنید.

برای یک درگیری مجدد، 409 را با «hint:» Use same Idempotency-Key یا GET status «».
Add 'Idempotency-Replay: true' when return a saved result.

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 s 'items: []، نه 404.
انتهای صفحه - «next _ page _ token» وجود ندارد.
نشانه نادرست - کد 400: PAGINATION_CURSOR_INVALID'.

9) Webhooks: تحویل قابل اعتماد

ثبت وقایع (HMAC) و بررسی قبل از پردازش.
پاسخ به پردازش موفق 2xx (بهترین 204) است.
دریافت کننده موقت شکست - 5xx ؛ فرستنده تکرار می شود (عقب نشینی نمایی، jitter).
Deduplication توسط 'event _ id' و صرفه جویی در نتیجه (مصرف کننده idempotent).
محموله نامعتبر - 400/422 بدون تلاش مجدد.

10) انطباق پروتکل (gRPC/GraphQL)

• 'INVALID _ ARGUMENT' → 400
• «تایید نشده» 401
• 'اجازه _ رد شد' → 403
• 'NOT _ FOUND' → 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 افسرده است').
'استهلاک', 'غروب', 'لینک: <...>; rel = «استهلاک» '- برای خاموش کردن کنترل شده.
'نوع مشکل' (سفارشی) - مسیریابی خطا سریع در مشتری.
'X-Trace-Id '/' Correlation-Id' - لینک سیاهههای مربوط/آثار.

12) امنیت پیام

اسرار ورودی (نشانه ها/امضاها) را در بدن پاسخ تکرار نکنید.
ماسک PAN/PII ('1234').
برای 401/403 - مشخص نکنید که کدام ویژگی شکست خورده است.
برای 404، به جای «منابع وجود دارد اما مال شما نیست» - فقط 404.

13) قابل مشاهده بودن خطاها

• 'http _ errors _ total {وضعیت، مسیر، مستاجر}'
• 'error _ classes _ total {code}' (با «کد» از بدن)
• سهم 429, 5xx; «p95 »/« p99» تاخیر برای پاسخ های اشتباه به طور جداگانه
• 'retry _ after _ seconds _ bucket' - هیستوگرام نکات تکرار

• پاسخ را با 'trace _ id', store 'code', 'type', 'status', 'route', 'tenant', no PII مرتبط کنید.

• spike '5xx _ rate> X٪' در RPS> N ؛
• رشد 429 در مسیرهای بحرانی ؛
• 'timeout/504' از وابستگی ها ؛
• تکرار 409/idempotency → نشانه ای از مسابقه.

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. 2409 (توانایی ایده آل)

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. 3429 (محدودیت)

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 های داخلی در 'detail'.
از «پیام» به جای «کد »/« نوع» پایدار استفاده کنید.
بازگشت 500 زمانی که یک خطای کسب و کار مورد انتظار رخ می دهد (به عنوان مثال، «تعادل کافی نیست»).
معناشناسی متناقض بین REST/GraphQL/gRPC.

16) ویژگی های iGaming/امور مالی

کدهای پاک برای KYC/AML/sanctions: «KYC _ REQUIRED», «KYC _ REVIEW», «AML _ LOCK», «SANCTION _ BLOCKED».
محدودیت های قضایی: 451 با متن امن بدون لیست.
عملیات نوشتن پولی: 409/423 برای رقابت و قفل، «اشاره» با یک پنجره مجدد.
بازیکن محدود ثابت: استفاده از 422 برای نقض مسئولیت پرداخت.
حسابرسی: سیاهههای مربوط به راه حل غیر قابل تغییر (کد، زمان، بازیگر، trace_id).

17) تولید لیست آمادگی

• طرح خطای JSON تنها، پایدار 'نوع '/' کد'.
• نقشه برداری HTTP ↔ gRPC/GraphQL سازگار و مستند است.
• Retray semantics + 'Retry-After' ؛ بی نظیر برای نوشتن.
• PII/ماسک مخفی ؛ 404 برای مخفی کردن منابع
• معیارهای خطا و هشدار ؛ همبستگی با 'trace _ id'.
• سیاستهای مستهلک: «استهلاک»، «غروب آفتاب»، «پیوند».
• تست: منفی/fuzz، درگیری نسخه، افت وابستگی، دو ارسال.
• راهنمای مشتری: نمونه های برگشتی و پردازش 409/422/429/5xx.

18) TL ؛ دکتر متخصص

استاندارد سازی یک فرمت خطای JSON با 'type '/' code '/' trace _ id'، استفاده از کدهای HTTP صحیح، تمایز بین اعتبار سنجی (400/422)، (401/403/404 حقوق)، درگیری/idempotency (409) و محدودیت (429). داده های حساس را پاک کنید، خطاهای ورود با «trace _ id» را وارد کنید و هشدارهای 5xx/429/p99 را ایجاد کنید.