הפרדת מצב, סוג ומקרה
RFC 9457 מגדיר application/problem+json. השתמשו בסוג בעיה יציב ובפירוט מובן למקרה; לקוח לא צריך לנתח משפט מתורגם כדי להחליט. שדה status, אם קיים, חייב להתאים למצב HTTP בפועל.
| מצב | משמעות HTTP | טיפול אפשרי |
|---|---|---|
| 400 | בקשה שגויה | תיקון לפני ניסיון נוסף. |
| 401 | חסרים פרטי אימות תקפים | בדיקת הפרטים והמנגנון המתועד. |
| 403 | הבקשה הובנה אך נדחתה | בדיקת זכויות; חזרה אינה מעניקה אותן. |
| 503 | השירות אינו זמין זמנית | המתנה וניסיונות מוגבלים אם הפעולה מאפשרת. |
מסלולי כשל צפויים
- תעדו קודים, פורמטים וטיפול נדרש. בדקו גם תשובות ריקות, תוכן שאינו JSON משער, ניתוקים ופקיעת זמן.
- אמתו קלט והרשאות בשרת. טפלו בכשלים צפויים בלי להסתיר תקלות לא מוכרות; אל תציגו כשל עסקי כהצלחה.
- החזירו מזהה מתאם לתמיכה. הוציאו עקבות מחסנית, שאילתות פנימיות, סיסמאות ואסימונים מתשובות ציבוריות.
לנסות שוב רק כשמתאים
5xx אינו מתיר לולאה ללא גבול. שלבו חוזה, מצב פעולה, אידמפוטנטיות וזמן כולל. דווחו תקלה בשחזור מזערי מנוקה; לאחר תיקון בדקו את המקרה המקורי ודחיות גישה סמוכות.
מקורות ראשוניים
שגיאות API צריכות להנחות פעולה ללא דליפה.
סטטוס HTTP מספק קטגוריה ראשונית, אך לקוח עשוי להזדקק לסוג יציב ופרטים שימושיים. RFC 9457 מתאר מבנה בעיה נפוץ; הוא אינו מצדיק חשיפת עקבות פנימיות או נתונים רגישים.
- סירוב קבוע נפרד, קלט ניתן לתיקון וכשל זמני.
- סוג מסמך, סטטוס ופעולת לקוח אפשרית עבור כל שגיאה חשובה.
- בדוק שהתשובות אינן מכילות סודות או מטענים מלאים מיותרים.
מקור ראשוני: IETF RFC 9457 — Problem Details for HTTP APIs. שיטה קשורה: קריאת המדריך המעשי.
ניסיונות API: לספור את מלוא תקציב הזמן
הגדירו גבול קריאות ומועד כולל.
מקרה לימודי בדוי: הנתונים אינם מתארים את CIE או לקוחות.
מודל בדוי: ארבע קריאות עד 250 מילישניות והמתנות 100, 200, 400. אינו כולל jitter, חיבור, תורים ובדיקה מקומית.
- כל הניסיונות
- 41 + 3
- סך המתנות (ms)
- 700100 + 200 + 400
- תקציב המודל (ms)
- 17004 × 250 + 700
| שלב | קריאה מרבית (ms) | המתנה הבאה (ms) |
|---|---|---|
| ניסיון 1 | 250 | 100 |
| ניסיון 2 | 250 | 200 |
| ניסיון 3 | 250 | 400 |
| ניסיון 4 | 250 | 0 |
| סך הכול | 1000 | 700 |
- זמן קריאות1,000
- המתנות מצטברות700
- מועד כולל (ms)1,500
בדיקות לפני מסקנה
- 1,000 + 700 = 1,700 חורג ממועד של 1,500 מילישניות.
- העבירו מועד כולל ומנעו השפעות כפולות; timeout אינו מוכיח ביטול מרוחק.
נסו תקציב ניסיונות
n × T + W × (2^(n−1) − 1)
שיטה קשורה: קריאת המדריך המעשי.
שגיאות API: סוגים, סטטוסים וראיות
הערות המקורות המפורטות זמינות באנגלית במהדורה זו.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5