एपीआई त्रुटि कोड और सर्वोत्तम अभ्यास

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

ग्राहकों के लिए पूर्वानुमान: एक एकल प्रारूप और रेट्रास का व्यवहार।

डिबग त्वरण: 'trace _ id '/' requess _ id', स्थिर 'त्रुटि _ code'.
सुरक्षा: SQL/स्टैक ट्रेस/कॉन्फ़िग लीक नहीं होगा.

अवलोकन: त्रुटि वर्गीकरण (सत्यापन, कोटा, टाइमआउट, आदि) पर रिपोर्टिंग।

2) बुनियादी सिद्धांत

1. सभी 4xx/5xx के लिए एक एकल प्रतिक्रिया प्रारूप (और आंशिक त्रुटियों के साथ 2xx के लिए - एक अलग योजना)।

2. साफ HTTP शब्दार्थ: सही स्थिति सबसे महत्वपूर्ण है।

3. कोड के दो स्तर: परिवहन ('स्थिति') और डोमेन स्थिर 'त्रुटि _ कोड'।

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

आवश्यक: 'प्रकार', 'शीर्षक', 'स्थिति', 'त्रुटि _ कोड', 'ट्रेस _ आईडी'.

वैकल्पिक: 'त्रुटियां []' (फ़ील्ड्स द्वारा), 'प्रतिशोधी', 'संकेत', 'मेटा'।

• 'सामग्री-प्रकार: एप्लिकेशन/समस्या + json'
• 'एक्स-रिक्वेस्ट-आईडी '/' ट्रेसपेरेंट' (W3C)
• (429/503 के लिए) 'रीट्री-आफ्टर' (सेकंड या डेट)

4) एचटीटीपी स्टेटस के शब्दार्थ ("क्लासिक्स" और अभ्यास का विलय)

2xx (सूक्ष्म सफलता)

200 ओके एक आम सफलता है।

201 बनाया गया - स्थान।

202 स्वीकार किया - कतार में अतुल्यकालिक रूप से ('स्थिति _ url' दें)।

207 बहु-स्थिति - आंशिक सफलता (यदि संभव हो तो बचें)।

4xx (क्लाइंट त्रुटि)

400 खराब अनुरोध - सिंटैक्स/प्रारूप, लेकिन क्षेत्र सत्यापन नहीं (अधिमानतः 422)।

401 अनधिकृत - नहीं/अमान्य टोकन। चलो 'WWW-Authenticate।'

403 वर्जित - टोकन वैध है, लेकिन पर्याप्त अधिकार नहीं हैं (आरबीएसी/एबीएसी/सीमाएं)।

404 नहीं मिला - कोई संसाधन/समापन बिंदु नहीं।

409 संघर्ष - इष्टतम लॉकिंग, पहचान।

410 गया - समापन बिंदु स्थायी रूप से हटा दिया गया।

412 पूर्व शर्त विफल - ETag/if-Match विफल।

415 असमर्थित मीडिया प्रकार - अवैध 'सामग्री-प्रकार'.

422 व्यापार नियमों का अप्रमाणित इकाई - सत्यापन।

429 बहुत से अनुरोध - कोटा/गति से अधिक (देखें)।

5xx (सर्वर त्रुटि)

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

502 खराब गेटवे - अपस्ट्रीम त्रुटि।

503 सेवा अनुपलब्ध - गिरावट/अधिभार, 'रेट्री-आफ्टर' देना।

504 गेटवे टाइमआउट - बैकेंड टाइमआउट।

5) डोमेन टैक्सोनॉमी 'त्रुटि _ कोड'

• 'AUTH _' - प्रमाणीकरण/प्राधिकरण।
• 'VAL _' - इनपुट डेटा का सत्यापन।
• 'RATELIMIT _' - कोटा और गति।
• 'IDEMP _' - idempotence/duplicates।
• 'COMPLENT _' - संस्करण/स्थि
• 'डीईपी _' - निर्भरता (पीएसपी/डीएनएस/एसएमटीपी)।
• 'PAY _' - भुगतान डोमेन की व्यापार त्रुटियां।
• 'एसईसी _' - सुरक्षा (हस्ताक्षर, एचएमएसी, एमटीएलएस)।
• 'INT _' - आंतरिक अचानक।

• समय के साथ स्थिरता (बैक-कॉम्पैट)।
• त्रुटि निर्देशिका में विवरण और उदाहरण (डॉक्स + मशीन-पढ़ने योग्य JSON)।

6) पुनर्प्राप्य बनाम गैर-पुनर्प्राप्य

• 'पुनर्विचार योग्य: सच' falsey '
• यदि 'सही' - आवश्यक रूप से 'रेट्री-आफ्टर' (सेकंड में) या अनुबंध "घातीय बैक-ऑफ (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'
• 'एक्स-रेटलिमिट-लिमिट', 'एक्स-रेटलिमिट-शेष', 'एक्स-रेटलिमिट-रीसेट'
• Для квот: 'एक्स-कोटा-लिमिट', 'एक्स-कोटा-शेष', 'एक्स-कोटा-रीसेट'

8) अज्ञानता और संघर्ष

लिखने के अनुरोधों में - 'आइडेम्पोटेंसी-की' (24-72 घंटे के भीतर अद्वितीय)।

'error _ code के साथ संघर्ष → 409 संघर्ष की कोशिश करें: "IDEMP_REPLAY"'।

ETag → 412 पूर्व शर्त के लिए संसाधन संस्करण संघर्ष विफल।

प्रतिक्रिया में, सुरक्षित पुन: अनुरोध के लिए 'resource _ id '/' state _ 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) के बीच अंतर करें।

11) सहसंबंध और अवलोकन

हमेशा 'ट्रेस _ आईडी '/' एक्स-रिक्वेस्ट- आईडी' जोड़ें और लॉग/ट्रैक के माध्यम से स्क्रॉल करें.

'error _ code' और 'status' → डैशबोर्ड "शीर्ष त्रुटियों", "नया बनाम ज्ञात" द्वारा कुल त्रुटियां।

अलर्ट: 5xx/422/429 स्पाइक, p95 विलंबता, त्रुटियों का हिस्सा।

12) gRPC/GraphQL/Webhooks - मैपिंग्स

gRPC ↔ HTTP

ग्राफ़क्यूएल

परिवहन 200, लेकिन 'त्रुटियां []' अंदर - जोड़ें 'एक्सटेंशन। कोड 'и' ट्रेस _ id '।

"घातक" (प्रमाणीकरण/कोटा) के लिए - एक वास्तविक HTTP 401/403/429 बेहतर है।

वेबहूक

केवल 2xx प्राप्तकर्ताओं को सफल मानें।

घातीय बैक-ऑफ के साथ रेट्राई, 'एक्स-वेबहुक-आईडी', 'एक्स-सिग्नेचर'।

प्राप्तकर्ता से 410 - स्टॉप रिट्रे (समापन बिंदु हटाया)।

13) त्रुटि सत्यापन

'टाइप '/' त्रुटि _ कोड' - स्थिर; नया - केवल जोड़ें।

बॉडी स्कीमा बदलते समय, एपीआई या 'समस्या + जेसन का मामूली संस्करण बढ़ाएं; 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।

अराजकता/विलंबता: 5xx/ 503/504/429 ('Retry-After') के लिए रिट्रे की जाँच कर रहा है।

सुरक्षा परीक्षण: कोई आंतरिक संदेश नहीं, पीआईआई मास्क सही करें।

बैकवर्ड-कॉम्पैट: पुराने ग्राहक नए क्षेत्रों को समझते हैं (जोड़ें, टूटें नहीं)।

16) कार्यान्वयन चेकलिस्ट

• एकल 'समस्या + json' + स्थिर 'त्रुटि _ कोड'।
• सही HTTP/gRPC/GraphQL शब्दार्थ।
• पुनर्प्राप्य/गैर-पुनर्प्राप्य + 'रीट्री-आफ्टर '/बैक-ऑफ सिफारिशें।
• दर-सीमा हेडर और 429 व्यवहार।
• आइडेम्पोटेंसी ('आइडेम्पोटेंसी-की', 409/412)।
• सुरक्षा: कोई ढेर निशान/रहस्य, पीआईआई संस्करण नहीं।
• सभी त्रुटियों में 'ट्रेस _ आईडी '/' एक्स-रिक्वेस्ट-आईडी'.
• त्रुटि सूची प्रलेखन और उदाहरण।
• त्रुटि वर्गीकरण द्वारा निगरानी।
• नकारात्मक परिदृश्यों के ऑटोटेस्ट।

17) मिनी-एफएक्यू

400 422 से कैसे अलग है?

400 - टूटा हुआ अनुरोध (वाक्यविन्यास/सामग्री प्रका 422 - सिंटैक्स में मान्य, लेकिन व्यापार नियम पारित नहीं किया।

401 कब है और 403 कब है?

401 - नहीं/गलत टोकन; 403 - एक टोकन है, वहाँ पर्याप्त अधिकार नहीं हैं।

क्या 'Retry-Afterways' की जरूरत है?

429/503 के लिए, हाँ; बाकी के लिए, पुनर्विचार - एक स्पष्ट सिफारिश देने के लिए उचित है।

कुल

अच्छी तरह से डिज़ाइन किए गए कीड़े अनुबंध हैं: सही HTTP स्थिति, एकल 'समस्या + json', स्थिर 'त्रुटि _ कोड', स्पष्ट रिट्रे संकेत और मजबूत सुरक्षा। प्रारूप को मानकीकृत करें, वर्गीकरण का दस्तावेज़ करें, टेलीमेट्री और परीक्षण जोड़ें - और आपका एपीआई अनुमानित, सुरक्षित और इंटीग्रेटर-फ्रेंडली हो जाता है।