קודי שגיאה של API והמנהגים הטובים ביותר

1) מדוע לעשות טעויות סטנדרטיות

חיזוי ללקוחות: תבנית אחת והתנהגות של רטראס.
תאוצת Debug: ”trace _ id'/” request' _ id', יציבה” שגיאה _ קוד ”.
אבטחה: SQL/מחסנית עקבות/תצורה לא ידלוף.
תצפית: דיווח על טקסונומיה שגויה (אימות, מכסות, פסקי זמן וכו ').

2) עקרונות בסיסיים

1. פורמט תגובה יחיד לכל 4xx/5xx (ועבור 2xx עם שגיאות חלקיות - סכימה נפרדת).
2. ברור סמנטיקה HTTP: המצב הנכון הוא החשוב ביותר.
3. שתי רמות של קוד: transport (”מצב”) ודומיין יציב ”שגיאה _ קוד”.
4. Retriable vs. Non-Retriable: לציין במפורש ולתת רמז על חזרה.
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"}
}

נדרש: "סוג", "שם", "סטטוס", "שגיאה _ קוד", "trace _ id'.
אופציונלי: ”שגיאות [ ]” (על ידי שדות), ”לאחזר”, ”רמז”, ”מטה”.

• תוכן-סוג: יישום/בעיה + ג 'סון &pos
• ”X-בקשה-זיהוי ”/” Traceparent” (W3C)
• (429/503) ”Retry-After” (שניות או תאריך)

4) סמנטיקה של סטטוסים של HTTP (מיזוג ”קלאסיקות” ופרקטיקה)

2xx (הצלחה בניואנסים)

200 אישור הוא הצלחה נפוצה.
201 נוצר - מיקום.
202 מתקבל - אסינכרוני בתור (תן 'סטטוס _ url').
207 Multi-States - הצלחה חלקית (להימנע במידת האפשר).

4xx (טעות הלקוח)

400 בקשה גרועה - תחביר/פורמט, אבל לא אימות שדה (רצוי 422).

401 לא מורשה - אסימון לא חוקי. בואו 'WWW-אותנטי. &post;

403 אסימון אסור תקף, אבל אין מספיק זכויות (RBAC/ABAC/limits).
404 לא נמצא - אין משאב/נקודת סוף.
409 סכסוך - נעילה אופטימלית, אידמפוטנטיות.
410 נעלם - סוף נקודה הוסרה לצמיתות.
412 תנאי מוקדם נכשל - ETag/IF-Match נכשל.
415 סוג מדיה לא נתמך - ”תוכן-סוג” לא תקף.
422 ישות בלתי ניתנת לעיבוד - אימות של כללים עסקיים.
429 יותר מדי בקשות - מעבר למכסות/מהירות (ראה # 7).

5xx (שגיאת שרת)

שגיאת שרת פנימית 500 - שגיאה פתאומית; לא לחשוף פרטים.
שער רע 502 - שגיאה במעלה הזרם.
503 שירות לא זמין - הידרדרות/עומס יתר, לתת ”Retry-After”.
פסק זמן של שער 504, פסק זמן אחורי.

5) טקסונומיה דומיין 'שגיאה _ code&pos

• 'AUTH' - אימות/אישור.
• VAL _ - אימות של נתוני קלט.
• 'RATELIMIT' - מכסות ומהירות.
• 'IDEMP _' - אידמפוטנטיות/כפילויות.
• עימות - גרסאות/סטטוס.
• 'DEP _' - תלויות (PSP/DNS/SMTP).
• ”שלם _” - טעויות עסקיות של תחום התשלום.
• 'SEC _ - אבטחה (חתימות, HMAC, mTLS).
• 'INT' - פתאומי פנימי.

• יציבות לאורך זמן (back-compat).
• תיאורים ודוגמאות בספריית השגיאות (docs + compliable-machine-readiable JSON).

6) Retriable vs. Non-Retribable

• ניתן לטעות: נכון &ft
• אם ”נכון” - בהכרח ”Retry-After” (בשניות) או חוזה ”back-off מעריכי (החל מ 1-2 s, מקסימום 30-60 s)”.

ניתן לאחזר בדרך כלל: ”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
}

• 'Retry-After: 12&fost
• 'X-Extlimit-Limite', 'X-Estlime-Lessons', X-Estlime-Reset&ft
• Limital: "X-Quota-Limit", "X-Quota-Lemain", "X-Quota-Resepos

8) אידמפוטנטיות וקונפליקטים

בקשות בכתב - 'Idempotency-Key' (ייחודי בתוך 24-72 שעות).
Treaty conflict # 409 conflict with 'error _ code: "IDEMP_REPLAY"'.
קונפליקט גרסת משאב עבור ETag * 412 Prediction נכשל.
בתגובה, צרף את a 'ressource _ 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, שבילי קובץ, שמות מארחים פרטיים.
ערוך את מח "ש; לפקוח עין על GDPR/DSAR.
לחתימה/HMAC, הבחנה בין 'SEC _ חתימה _ MISMATCH' (403) ו- 'SEC _ TIMESTAMP _ SKEW' (401/403) עם הפקודה ”check intime 5 min”.

11) קורלציה ויכולת תצפית

תמיד הוסף "trace _ id'/" X-Request-ID" וגלול דרך הרישומים/רצועות.
שגיאות צבירה על ידי 'טרור _ קוד' ו 'סטטוס' * לוחות מחוונים ”טעויות עליונות”, ”נגד חדש ידוע”.
התראות: 5xx/422/429 ספייק, p95 latency, שיתוף שגיאות.

12) gRPC/GraphQL/Webhooks - מפיות

GRPC ↔ HTTP

GraphQL

תחבורה 200, אבל ”טעויות [ ]” בפנים - להוסיף 'חריצות. קוד "trace _ id'.
עבור ”קטלני” (אימות/מכסות) - 401/403/429 HTTP אמיתי הוא טוב יותר.

Webhooks

קחו בחשבון רק מקבלי 2xx מוצלחים.
רטריי עם גיבוי מעריכי, ”X-Webhook-ID”, ”X-חתימה”.
410 מהמקבל - עצור מגש מחדש (סוף נקודה הוסרה).

13) שגיאה במהלכה

”type ”/” טעות _ קוד” - יציב; חדש - רק להוסיף.
בעת שינוי סכימת הגוף, להעלות את הגרסה המינורית של 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) בדיקה ואיכות

חוזה מבחן: התאמת ”application/problem + json”, שדות דרושים.
בדיקות שליליות: כל הענפים 401/403/404/ 409/422/429/500.
כאוס/איחור: בדיקה מחדש עבור 5xx/ 503/504/429 (”Retry-After”).
בדיקות אבטחה: אין הודעות פנימיות, נכון מסכת מח "ש.
לקוחות ישנים מבינים שדות חדשים (הוסף, אל תישבר).

16) רשימת מימושים

[ ] בעיה אחת + json '+ יציבה' שגיאה _ קוד '.

[ ] נכון HTTP/gRPC/GRPQL.

[ ] רטריאביליות/לא ניתנות לאחזור + ”Retry-After ”/Back-off המלצות.

[ ] הגבלת קצב כותרות והתנהגות 429.

[ ] אידמפוטנטיות (Idempotency-Key, 409/412).

[ ] אבטחה: אין עקבות/סודות, מהדורת מח "ש.

[ ] 'trace _ id'/' X-Request-ID' בכל הטעויות.

[ ] שגיאות קטלוג תיעוד ודוגמאות.

[ ] ניטור באמצעות טקסונומיה שגויה.

[ ] תרחישים שליליים.

17) מיני ־ FAQ

במה שונה 400 מ-422?
400 - בקשה שבורה (סוג תחביר/תוכן). 422 - תקף בתחביר, אבל כללי עסקים לא עברו.

מתי 401 ומתי 403?
401 - אסימון לא נכון; 403 - יש אסימון, אין מספיק זכויות.

האם "Retry-After 'Always צורך?
עבור 429/503, כן; עבור השאר, ניתן לאחזר - מומלץ לתת המלצה מפורשת.

סך הכל

באגים מעוצבים היטב הם החוזה: נכון מצב HTTP, יחיד ”בעיה + json”, יציב ”שגיאה _ קוד”, רמזים מגשים מחדש מפורשים, וביטחון חזק. תקן את הפורמט, תיעד את הטקסונומיה, תוסיף טלמטריה ומבחנים, והמכשיר שלך יהיה צפוי, מאובטח וידידותי לאינטגרטור.