שגיאה בטיפול וקודי מצב

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

• הצפוי מקודד סוג של בעיה,
• נותן ללקוח הוראות תקפות (מה לעשות הלאה),
• מגן מפני דליפה של חלקים פנימיים,
• תואם עם רטראס ואידמפוטנטיות.

2) עקרונות עיצוב

1. ערכת שגיאה אחת לכל השירותים (REST/GRPC/webhooks).
2. סמנטיקה ברורה של מגשים מחדש: איזה קודים לסגת, אשר לא.
3. כשל סגור על פעולות כתיבה: עדיף 4xx/5xx מאשר חוסר עקביות שקט.
4. אין דליפות: אין לחשוף SQL, ערימות, הגדרות, תעודות זהות פנימיות.
5. עקבות - תמיד לחזור ”trace _ id'/” correlation _ id'.
6. לוקליזציה של הודעות היא אופציונלית, אבל קודים ו 'ריסון' להישאר יציב.

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' הוא כתובת כיתת טעות יציבה.
• קוד - קוד מכונת תחום קצר (יציב בין שחרור).
• רמז '- מה לעשות עבור הלקוח (חוזר, עדכון אסימון, שינוי פרמטרים).
• 'meta' - חלקים מאובטחים (ללא סודות ו PII).

4) מפת קוד מצב (סט מינימלי)

אימות/אישור

400 בקשה גרועה - אימות מבני/תרמית.
401 לא מורשה - אסימון לא חוקי. הוסף ”WWW-אימות”.
403 אסור - מאומת אבל אין זכויות/מדיניות נשללת.
404 לא נמצא - מסווה את קיומו של משאב ללא זכויות.
סכסוך 409 - גרסה/מצב (נעילה אופטימית, אידמפוטנטיות).
451 לא זמין מסיבות משפטיות - ציות/שיפוט בלוק.

גבולות והגנה

בקשות 408, הלקוח שולח את הגופה לאט מדי.
409/425 מוקדם מדי - איסור על חזרה מוקדמת 0-RTT/TLS 1. 3.
429 יותר מדי בקשות - עם ”Retry-After” והגבלת מדיניות.
499 בקשה סגורה לקוח - (במתחם/NGINX) הלקוח ניתק את החיבור.

נתונים וכללים עסקיים

422 תוכן בלתי ניתן לעיבוד - אישור עסקי עבר את המזימה, אבל המשמעות היא שגויה.
423 משאב נעול חסום (ביקורת KYC, AML להקפיא).
409 קונפליקט - כניעה כפולה, גזע, הגבלת מעמד (לדוגמה, ”כבר בתהליך”).
410 Gone - endpoint/resource נמחק (despression הושלם).

שרת

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

5) מגש מחדש וסמנטיקה אידמפוטנטיות

אתה לא יכול לחזור בך 400/ 401/403/404/422 (אלא אם הלקוח שינה את הבקשה).
באפשרותך לחזור: 408/429/5xx/ 425/499/504 (עם backoff + jitter).
Idempotency: FOR 'POSt', אפשר' Idempotency-Key '(UUIDv4).

עבור עימות חוזר, להחזיר 409 עם רמז: ”השתמש באותו מפתח אידמפוטנטי או לקבל מעמד”.
הוסף 'Idempotency-Replay: אמיתי' כאשר חוזר תוצאה ניצלה.

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 פריטים: [ ] ", לא 404.
סוף העמוד - 'next _ page _ token' חסר.
לא נכון, קוד 400: PAGINATION_CURSOR_INVALID'.

9) חוברות אינטרנט: משלוח אמין

לחתום על אירועים (HMAC) ולבדוק לפני עיבוד.
התגובה לעיבוד מוצלח היא 2xx (204 הטוב ביותר).
כשלים זמניים במקלט - 5xx; השולח חוזר על עצמו (גיבוי מעריכי, ג 'יטר).
שכפול על ידי 'event _ id' ושמירת התוצאה (צרכן אידמפוטנטי).
מטען לא תקין - 400/422 אין חזרה.

10) פרוטוקול קונפורמנס (GRPC/GraphQL)

• ”לא תקף _ ויכוח” ”400”
• ”לא מפותה” * 401
• 'אישור _ נדחה' * 403
• ”לא נמצא” * 404
• ”כבר _ קיים” * 409
• ”נכשל _ PRECONDITION” * 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 מדוכא”).
"פיחות", "שקיעה", "קישור: <...> ריל = ”ירידה” - לכיבוי מבוקר.
'בעיה-סוג' (מותאם אישית) - שגיאה מהירה ניתוב על הלקוח.
”X-Trace-Id'/” Correlation-Id' - קישורים יומנים/עקבות.

12) ביטחון הודעה

אל תחזור על סודות הקלט בגוף התגובה.
מסכה פאן/פיי ('1234').
עבור 401/403 - אל תגלה איזה מאפיין נכשל.
עבור 404, במקום ”משאב קיים אבל לא שלך” - רק 404.

13) יכולת תצפית על טעויות

• ”http _ שגיאות _ status הכולל, מסלול, דייר”
• 'errior _ class _ total _ code' (על ידי 'code' מהגוף)
• לחלוק 429, 5xx; p95 '/p99 'latensy לתשובות שגויות בנפרד
• 'retry _ after _ seconds _ buit' - היסטוגרמה של עצות החזרה

• לקשר את התגובה עם "trace _ id', לאחסן 'קוד', 'type', 'status', 'route', 'derant', אין PII.

• Spike '5xx _ rate> X%' at RPS> N;
• גידול של 429 בנתיבים קריטיים;
• פסק זמן/504 &post של תלות;
• 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. 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/שמות טבלה/כתובות פנימיות ב- detail.
השתמש ב ”הודעה” במקום ”קוד יציב ”/” סוג”.
החזר 500 כאשר תתרחש שגיאה עסקית צפויה (לדוגמה, ”שיווי משקל אינו מספיק”).
סמנטיקה לא עקבית בין REST/GRPC.

16) פרטים של iGaming/Finance

קודים נקיים עבור KYC/AML/סנקציות: ”KYC _ Designed”, ”KYC _ Review”, ”AML _ LOCK”, ”SANTION _ BLOCK”.
הגבלות שיפוט: 451 עם ניסוח מאובטח ללא רישום.
פעולות כתיבה כספית: 409/423 לתחרות ומנעולים, ”רמז” עם חלון מחדש.
הגבלת שחקנים: השתמש ב ־ 422 לעבירות תשלום אחראיות.
ביקורת: יומני פתרון בלתי ניתנים לשינוי (קוד, זמן, שחקן, trace_id).

17) רשימת מוכנות למומחים

[ ] שגיאות JSON יחיד, יציב ”סוג '/' קוד”.

[ ] HTTP ↔ gRPC/GraphQL הוא עקבי ומתועד.

[ ] Retray Semantics + ”Retry-After”; חוסר אונים לכתיבה.

[ ] PII/מסווה סודי; 404 להסתיר משאבים.

[ ] שגיאות ומדדי התראה; מתאם עם "trace _ id'.

[ מדיניות הפחת ]: ”פיחות”, ”שקיעה”, ”לינק”.

[ ] בדיקות: שלילי/פלומה, קונפליקט גרסה, ירידה תלות, כפולה להיכנע.

[ ] מדריך לקוחות: דוגמאות לאחור ועיבוד 409/422/429/5xx.

18) TL; DR

תקן פורמט שגיאת JSON יחיד עם 'type '/' code '/' trace _ id', השתמש בקודי HTTP נכונים, להבחין בין אימות (400/422), זכויות (401/403/404), קונפליקטים/אידמפוטנטיות (409) ומגבלות (429). תן ברור "Retry-After" ו "רמז", מסכת מידע רגיש, רישום שגיאות עם "trace _ id' ובנה התראות על ידי 5xx/429/p99.