हैंडलिंग और स्थिति कोड में त्रुटि

1) त्रुटियों को मानकीकृत क्यों करें

• अनुमानित रूप से समस्या के प्रकार को एनकोड करता है,
• ग्राहक को वैध संकेत देता है (आगे क्या करना है),
• आंतरिक भागों के रिसाव से बचाता है,
• रेट्रास और पहचान के साथ संगत।

2) डिजाइन सिद्धांत

1. सभी सेवाओं के लिए एक त्रुटि योजना (REST/graphQL/gRPC/webhook)।

2. रिट्रेज़के शब्दार्थ स्पष्ट करें: कौन से कोड वापस लेने के लिए हैं, जो नहीं।

3. लेखन संचालन पर विफल-बंद: शांत असंगति की तुलना में बेहतर 4xx/5xx।

4. कोई लीक नहीं: SQL, स्टैक, कॉन्फ़िग, आंतरिक आईडी का खुलासा न करें।

5. ट्रेस - हमेशा 'ट्रेस _ आईडी '/' सहसंबंध _ आईडी' वापस करें।

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"
}
}

• 'टाइप' एक स्थिर त्रुटि वर्ग URL है।
• 'कोड' - शॉर्ट डोमेन मशीन कोड (रिलीज के बीच स्थिर)।
• 'संकेत' - क्लाइंट के लिए क्या करना है (दोहराएं, अपडेट टोकन, पैरामीटर बदलें)।
• 'मेटा' - सुरक्षित भागों (बिना रहस्य और पीआईआई के)।

4) स्थिति कोड मानचित्र (न्यूनतम सेट)

सत्यापन/प्राधिकरण

400 खराब अनुरोध - संरचनात्मक सत्यापन/योजना।

401 अनधिकृत - नहीं/अमान्य टोकन। 'WWW-प्रमाणीकरण' जोड़ें।

403 निषिद्ध - प्रमाणित लेकिन कोई अधिकार/नीतियां अस्वीकार नहीं।

404 नहीं मिला - बिना अधिकारों के संसाधन के अस्तित्व को मुखौटा।

409 संघर्ष - संस्करण/राज्य संघर्ष (आशावादी ताला, पहचान)।

451 कानूनी कारणों से अनुपलब्ध - अनुपालन/अधिकार क्षेत्र खंड।

सीमा और सुरक्षा

408 अनुरोध टाइमआउट - ग्राहक शरीर को बहुत धीरे-धीरे भेज रहा है।

409/425 बहुत जल्दी - 0-RTT/TLS 1 में शुरुआती दोहराव का निषेध। 3.

429 बहुत से अनुरोध - 'रीट्री-आफ्टर' और सीमा नीति के साथ।

499 क्लाइंट क्लोज्ड रिक्वेस्ट - (परिधि/NGINX पर) क्लाइंट ने कनेक्शन को काट दिया।

डेटा और व्यापार नियम

422 अप्रमाणित सामग्री - व्यापार सत्यापन ने योजना पारित की, लेकिन अर्थ गलत है।

423 लॉक - संसाधन अवरुद्ध (केवाईसी समीक्षा, एएमएल फ्रीज)।

409 संघर्ष - डबल सबमिशन, रेस, स्थिति सीमा (उदाहरण के लिए, "पहले से ही प्रक्रिया में")।

410 गया - समापन बिंदु/संसाधन विलोपित (पदावनत पूर्ण)।

सर्वर

500 आंतरिक सर्वर त्रुटि - अज्ञात त्रुटि; विवरण का खुलासा नहीं।

502 खराब गेटवे - निर्भरता ने त्रुटि/प्रॉक्सी लौटा दी।

503 सेवा अनुपलब्ध - क्षरण/योजनाबद्ध कार्य; 'रीट्री-आफ्टर' जोड़ें।

504 गेटवे टाइमआउट।

5) रिट्रे और पहचान शब्दार्थ

आप 400/ 401/403/404/422 वापस नहीं ले सकते (जब तक ग्राहक ने अनुरोध नहीं बदल दिया है)।

आप पीछे हट सकते हैं: 408/429/5xx/ 425/499/504 (बैकऑफ + जिटर के साथ)।

पहचान: 'POST' के लिए, 'Idempotency-Key' (UUIDv4) सक्षम करें।

एक पुनरावृत्ति संघर्ष के लिए, 'संकेत के साथ 409 वापस करें: "एक ही आइडेम्पोटेंसी-की या जीईटी स्थिति का उपयोग करें"।

जोड़ें 'Idempotency-Repay: सही' wheen एक बचाया परिणाम वापस।

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 s 'कोड: PAGINATION_CURSOR_INVALID'।

9) वेबहूक: विश्वसनीय वितरण

घटनाओं पर हस्ताक्षर करें (HMAC) और प्रसंस्करण से पहले जांचें।

सफल प्रसंस्करण की प्रतिक्रिया 2xx (सर्वश्रेष्ठ 204) है।

रिसीवर अस्थायी विफलताएं - 5xx; प्रेषक दोहराता है (घातीय बैकऑफ, जिटर)।

'ईवेंट _ आईडी' द्वारा डीडुप्लीकेशन और परिणाम की बचत (पहचान करने वाला उपभोक्ता)।

अवैध पेलोड - 400/422 कोई पुनरावृत्ति नहीं।

10) प्रोटोकॉल अनुरूपता (जीआरपीसी/ग्राफक्यूएल)

• 'अवैध _ आर्गनाइजेशन' → 400
• 'UNAUTHENTICATED' → 401
• 'अनुमति _ DENED' → 403
• 'NOT _ FOUNED' → 404
• 'पहले से ही _ EXISTS' → 409
• 'FELED _ PRECONDITION' → 412/422
• 'रिसोर्स _ EXHAUSTED' → 429
• 'ABORTED' → 409
• 'अनुपलब्ध' → 503
• 'डेडलाइन _ EXCEEED' → 504

json
{
"data": { "createPayment": null },
"errors": [{
"message": "Forbidden",
"extensions": { "code": "FORBIDDEN", "status": 403, "trace_id": "..." },
"path": ["createPayment"]
}]
}

महत्वपूर्ण त्रुटियों के लिए 200 के बजाय संबंधित HTTP कोड का उपयोग करने की सिफारिश की जाती है।

11) टाइटल और ग्राहक टिप्स

'रीट्री-आफ्टर' - सेकंड/HTTP तिथि (429/503/425/408)।

'चेतावनी' - नरम गिरावट या मूल्यह्रास ("199 - फीचर एक्स उदास है")।

'डिप्रेशन', 'सनसेट', 'लिंक: <...>; rel = "deprecation" '- नियंत्रित शटडाउन के लिए।

'समस्या-प्रकार' (कस्टम) - क्लाइंट पर तेजी से त्रुटि मार्ग।

'एक्स-ट्रेस-आईडी '/' सहसंबंध-आईडी' - लिंक लॉग/ट्रेस।

12) संदेश सुरक्षा

प्रतिक्रिया निकाय में इनपुट सीक्रेट (टोकन/हस्ताक्षर) दोहराएँ नहीं।

मास्क पैन/पीआईआई ('1234')।

401/403 के लिए - यह खुलासा न करें कि कौन सा गुण विफल रहा।

404 के लिए, "संसाधन मौजूद है, लेकिन आपका नहीं" - सिर्फ 404।

13) त्रुटियों का अवलोकन

• 'http _ errors _ कुल {स्थिति, मार्ग, किरायेदार}'
• 'error _ वर्ग _ कुल {कोड}' (शरीर से 'कोड' द्वारा)
• शेयर 429, 5xx; गलत उत्तरों के लिए 'p95 '/' p99' विलंबता अलग से
• 'retry _ after _ sext _ bult' - पुनरावृत्ति युक्तियों के हिस्टोग्राम

• 'ट्रेस _ आईडी', स्टोर 'कोड', 'टाइप', 'स्टेटस', 'रूट', 'किरायेदार', नो पीआईआई के साथ प्रतिक्रिया को जोड़ें।

• आरपीएस> एन में स्पाइक '5xx _ दर> X%';
• महत्वपूर्ण मार्गों पर 429 की वृद्धि;
• 'टाइमआउट/504' of निर्भरता;
• अक्सर 409/पहचान - रेसिंग का संकेत।

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/टेबल नाम/आंतरिक URL का विस्तार करें।

स्थिर 'कोड '/' प्रकार' के बजाय 'संदेश' का प्रयोग करें।

जब एक अपेक्षित व्यावसायिक त्रुटि होती है तो 500 वापस करें (उदाहरण के लिए, "संतुलन अपर्याप्त है

REST/GraphQL/gRPC के बीच असंगत शब्दार्थ।

16) iGaming/वित्त की विशिष्टताएँ

KYC/AML/प्रतिबंधों के लिए स्पष्ट कोड: 'KYC _ आवश्यक', 'KYC _ REVIVE', 'AML _ LOCK', 'SANCTION _ BROLKLANDED D ED ED ED S.

क्षेत्राधिकार प्रतिबंध: सूची के बिना सुरक्षित शब्द के साथ 451।

मौद्रिक लेखन संचालन: प्रतियोगिता और ताले के लिए 409/423, एक फिर से खिड़की के साथ 'संकेत'।

खिलाड़ी सीमा अपरिवर्तनीय: जिम्मेदार भुगतान उल्लंघन के लिए 422 का उपयोग करें।

लेखा परीक्षा: अपरिवर्तनीय समाधान लॉग (कोड, समय, अभिनेता, trace_id)।

17) प्रोड रेडीनेस चेकलिस्ट

• एकल JSON त्रुटि योजना, स्थिर 'प्रकार '/' कोड'।
• HTTP ↔ gRPC/GraphQL मैपिंग सुसंगत और प्रलेखित है।
• रिट्रे शब्दार्थ + 'रीट्री-आफ्टर'; लिखने के लिए पहचान।
• पीआईआई/गुप्त मास्किंग; संसाधनों को छिपाने के लिए 404।
• त्रुटि और सतर्क मैट्रिक्स; 'ट्रेस _ आईडी' के साथ सहसंबंध।
• पदावनत नीतियां: 'Deprecation', 'Sunset', 'Link'।
• टेस्ट: नकारात्मक/फ़ज़, संस्करण संघर्ष, निर्भरता ड्रॉप, डबल-सबमिट।
• ग्राहक गाइड: बैक-ऑफ उदाहरण और 409/422/429/5xx प्रसंस्करण।

18) टीएल; डीआर

'प्रकार '/' कोड '/' ट्रेस _ आईडी' के साथ एकल JSON त्रुटि प्रारूप का मानकीकरण करें, सही HTTP कोड का उपयोग करें, सत्यापन (400/422), अधिकार), विरोध/पहचान (409), और सीमा (429)। 'Retry-After' और 'संकेत', मास्क सेंसिटिव डाटा, लॉग त्रुटियां 'trace _ id' के साथ दें और 5xx/429/p99 द्वारा अलर्ट बनाएँ.