کدهای خطای API و بهترین شیوه ها

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

پیش بینی برای مشتریان: یک فرمت واحد و رفتار retras.
شتاب اشکال زدایی: 'trace _ id '/' request _ id'، پایدار 'error _ code'.
امنیت: ردیابی/پیکربندی SQL/پشته نشت نخواهد کرد.
قابلیت مشاهده: گزارش در طبقه بندی خطا (اعتبار سنجی، سهمیه، زمان بندی، و غیره).

2) اصول اساسی

1. یک فرمت پاسخ واحد برای همه 4xx/5xx (و برای 2xx با خطاهای جزئی - یک طرح جداگانه).
2. پاک کردن معانی HTTP: وضعیت صحیح مهم است.
3. دو سطح کد: حمل و نقل («وضعیت») و دامنه پایدار «error _ code».
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"}
}

مورد نیاز: 'type'، 'title'، 'status'، 'error _ code'، 'trace _ id'.
اختیاری: «خطاها []» (توسط زمینه ها)، «قابل بازیابی»، «اشاره»، «متا».

• 'Content-Type: application/problem + json'
• 'X-Request-ID '/' Traceparent' (W3C)
• (برای 429/503) 'Retry-After' (ثانیه یا تاریخ)

4) معانی وضعیت HTTP (ادغام «کلاسیک» و عمل)

2XX (موفقیت ظریف)

200 OK یک موفقیت مشترک است.
201 ایجاد شده - محل.
202 پذیرفته شده - به صورت ناهمگام در صف (به 'status _ url').
207 چند وضعیت - موفقیت جزئی (اجتناب از در صورت امکان).

4xx (خطای مشتری)

۴۰۰ Bad Request - syntax/format, but not field validation (ترجیحا ۴۲۲).
401 توکن غیر مجاز - بدون/نامعتبر. بیایید «WWW-Authenticate» را بررسی کنیم.
۴۰۳ Forbidden - توکن معتبر است، اما حقوق کافی وجود ندارد (RBAC/ABAC/limits).
404 یافت نشد - هیچ منبع/نقطه پایانی وجود ندارد.
409 تعارض - قفل بهینه، idemotency.
۴۱۰ Gone - نقطه پایانی به طور دائم حذف شده است.
412 پیش شرط شکست خورده - ETag/If-Match شکست خورده است.
415 نوع رسانه پشتیبانی نشده - نامعتبر «محتوا نوع».
422 نهاد غیر قابل پردازش - اعتبار قوانین کسب و کار.
429 Too Many Requests - بیش از سهمیه/سرعت (نگاه کنید به § 7).

5xx (خطای سرور)

500 خطای سرور داخلی - خطای ناگهانی ؛ جزئیات را فاش نکند.

خطای 502 Bad Gateway - Upstream

503 سرویس در دسترس نیست - تخریب/اضافه بار، به 'Retry-After'.
504 اتمام وقت دروازه - اتمام وقت باطن.

5) طبقه بندی دامنه 'error _ code'

• 'AUTH _' - احراز هویت/مجوز.
• 'VAL _' - اعتبار سنجی داده های ورودی.
• 'RATELIMIT' - سهمیه و سرعت.
• 'IDEMP _' - idempotence/تکراری.
• 'CONFLICT _' - نسخه/وضعیت.
• 'DEP _' - وابستگی ها (PSP/DNS/SMTP).
• «PAY» - خطاهای تجاری دامنه پرداخت.
• 'SEC _' - امنیت (امضا، HMAC، mTLS).
• 'INT' - ناگهانی داخلی.

• پایداری در طول زمان (back-compat).
• توضیحات و نمونه ها در دایرکتوری خطا (docs + 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-RateLimit-Remaining', 'X-RateLimit-Reset'
• Для квот: «X-Quota-Limit»، «X-Quota-Remaining»، «X-Quota-Reset»

8) ناتوانی و درگیری

درخواست نوشتن - 'Idempotency-Key' (منحصر به فرد در عرض 24-72 ساعت).
ناسازگاری → 409 ناسازگاری با «error _ code:» IDEMP_REPLAY"'.
ناسازگاری نسخه منبع برای ETag → 412 پیش شرط شکست خورد.
در پاسخ، ضمیمه 'resource _ id '/' status _ 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 ؛ به GDPR/DSAR توجه کنید.
برای امضا/HMAC، بین «SEC _ SIGNATURE _ MISMATCH» (403) و «SEC _ TIMESTAMP _ SKEW» (401/403) با اعلان «check ± time 5 min» تمایز قائل شوید.

11) همبستگی و قابلیت مشاهده

همیشه «trace _ id »/« X-Request-ID» را اضافه کنید و از طریق سیاهههای مربوط/آهنگ حرکت کنید.
خطاهای مجموع توسط «error _ code» و «status» → داشبورد «خطاهای بالا»، «جدید در مقابل شناخته شده».
هشدارها: سنبله 5xx/422/429، تأخیر p95، سهم خطاها.

12) gRPC/GraphQL/Webhooks - نقشه ها

gRPC ↔ HTTP

GraphQL

حمل و نقل 200، اما 'errors [] در داخل - اضافه کردن extensions. کد 'и' trace _ id '.
برای «کشنده» (احراز هویت/سهمیه) - یک 401/403/429 HTTP واقعی بهتر است.

صفحات وب

فقط دریافت کنندگان 2xx موفق هستند.
«X-Webhook-ID»، «X-Signature».
410 از گیرنده - توقف retray (نقطه پایانی حذف شده).

13) نسخه خطا

'type '/' error _ code' - stable; جدید - فقط اضافه کنید

هنگام تغییر طرح بدنه، نسخه جزئی API یا "problem + 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) تست و کیفیت

قرارداد تست: مطابقت 'نرم افزار/مشکل + json'، زمینه های مورد نیاز.
تست منفی: تمام شاخه های 401/403/404/ 409/422/429/500.
هرج و مرج/تاخیر: چک کردن retrays برای 5xx/ 503/504/429 ('Retry-After').
تست های امنیتی: بدون پیام داخلی، ماسک PII صحیح.
کامپات عقب مانده: مشتریان قدیمی زمینه های جدید را درک می کنند (اضافه کردن، شکستن).

16) چک لیست پیاده سازی

• تنها 'مشکل + json' + پایدار 'error _ code'.
• معانی HTTP/gRPC/GraphQL را درست کنید.
• قابل بازیابی/غیر قابل بازیابی + 'Retry-After '/توصیه های برگشت.
• هدر نرخ محدود و رفتار 429.
• Idempotency («Idempotency-کلید»، 409/412).
• امنیت: هیچ اثری/اسرار پشته، نسخه PII.
• 'trace _ id '/' X-Request-ID' در تمام خطاها.
• مستندات کاتالوگ خطا و نمونه.
• نظارت بر طبقه بندی خطا.
• نشانه های سناریوهای منفی.

17) مینی سوالات متداول

400 چه تفاوتی با 422 دارد ؟

400 - درخواست شکسته (نحو/نوع محتوا). ۴۲۲ - در نحو معتبر است، اما قوانین کسب و کار تصویب نشده است.

401 چه زمانی است و 403 چه زمانی است ؟

401 - نشانه بدون/نادرست ؛ ۴۰۳ - یک نشانه وجود دارد، حقوق کافی وجود ندارد.

آیا «بازگشت» همیشه لازم است ؟

برای 429/503، بله ؛ برای بقیه، قابل بازیابی است - توصیه می شود یک توصیه صریح ارائه دهید.

مجموع

اشکالات به خوبی طراحی شده قرارداد هستند: وضعیت HTTP صحیح، تنها «مشکل + json»، پایدار «error _ code»، نکات صریح retray و امنیت قوی. فرمت را استاندارد کنید، طبقه بندی را مستند کنید، تله متری و تست ها را اضافه کنید - و API شما قابل پیش بینی، امن و یکپارچه می شود.