दोनों ResQ APIs मानक HTTP स्टेटस कोड का उपयोग करते हैं और विफलता पर एक छोटा
JSON एनवेलप लौटाते हैं। स्टेटस कोड को प्रामाणिक मानें; बॉडी लॉग और ऑपरेटर
सतहों के लिए डायग्नोस्टिक विवरण है — फ्लो कंट्रोल के लिए नहीं।
एनवेलप
Infrastructure API लौटाता है:
{ "error": "Invalid credentials" }
Coordination API समान आकार लौटाता है, या एक से अधिक विफलता रिपोर्ट करने
वाले एंडपॉइंट पर एक समृद्ध एनवेलप:
{
"error": "validation_failed",
"message": "field 'mission_id' is required",
"details": [
{ "path": "mission_id", "rule": "required" }
]
}
हमेशा HTTP स्टेटस कोड पर शाखा बनाएँ। बॉडी के अंदर फ़ील्ड नाम विकसित हो
सकते हैं; स्टेटस कोड स्थिर हैं।
स्टेटस कोड
| कोड | नाम | अर्थ |
|---|
200 | OK | सफलता। |
201 | Created | एक नया संसाधन बनाया गया (उदा. साक्ष्य अपलोड)। |
202 | Accepted | अनुरोध कतारबद्ध — आमतौर पर टेलीमेट्री या एसिंक काम। |
204 | No Content | बॉडी के बिना सफलता। |
400 | Bad Request | विकृत JSON या अमान्य पैरामीटर। |
401 | Unauthorized | टोकन गायब, समाप्त, या अमान्य। |
403 | Forbidden | टोकन में संसाधन के लिए आवश्यक स्कोप नहीं। |
404 | Not Found | संसाधन मौजूद नहीं या आपके ऑपरेटर को दिखाई नहीं देता। |
409 | Conflict | संसाधन की स्थिति ऑपरेशन रोकती है (उदा. मिशन पहले से अनुमोदित)। |
422 | Unprocessable Entity | अच्छी तरह बने अनुरोध पर सत्यापन विफल। |
429 | Too Many Requests | रेट लिमिट पार। Retry-After का सम्मान करें। |
500 | Internal Server Error | अप्रत्याशित सर्वर दोष। रिट्राई सुरक्षित। |
503 | Service Unavailable | अपस्ट्रीम निर्भरता डिग्रेड। बैकऑफ के साथ रिट्राई सुरक्षित। |
क्या रिट्राई करें
| क्लास | रिट्राई? | रणनीति |
|---|
4xx (408, 409, 429 को छोड़कर) | नहीं | अनुरोध ठीक करें। |
408 Request Timeout | हाँ | एक रिट्राई। |
409 Conflict | कभी-कभी | स्थिति फिर पढ़ें, फिर निर्णय करें। |
429 Too Many Requests | हाँ | Retry-After का सम्मान करें, फिर जिटर के साथ एक्सपोनेंशियल बैकऑफ। |
5xx | हाँ | जिटर के साथ एक्सपोनेंशियल बैकऑफ, ~30 सेकंड पर सीमित। |
बैकऑफ स्केच
async function withRetry<T>(fn: () => Promise<T>, max = 4): Promise<T> {
let attempt = 0;
while (true) {
try {
return await fn();
} catch (err: any) {
const status = err?.status ?? 0;
const retryable = status === 429 || status >= 500;
if (!retryable || attempt >= max) throw err;
const base = 250 * 2 ** attempt;
const jitter = Math.random() * base;
await new Promise((r) => setTimeout(r, base + jitter));
attempt++;
}
}
}
सामान्य त्रुटियाँ
401 Unauthorized
{ "error": "Token expired" }
प्रमाणीकरण में वर्णित लॉगिन प्रवाह को पुनः चलाएँ
और अनुरोध को एक बार रिट्राई करें।
403 Forbidden
{ "error": "Insufficient scope: missions.approve" }
ऑपरेटर प्रमाणित है लेकिन उसके पास आवश्यक स्कोप नहीं है। उपयोगकर्ता को
दिखाएँ; रिट्राई न करें। मिशन-अनुमोदन प्रवाह विशेष रूप से HITL-अधिकृत
ऑपरेटर की आवश्यकता रखते हैं (EU AI अधिनियम धारा 14)।
429 Too Many Requests
प्रतिक्रिया में Retry-After हेडर शामिल है जो प्रतीक्षा सेकंड बताता है।
रिट्राई से पहले कम से कम उतना समय रुकें।
503 Service Unavailable
मेश या अपस्ट्रीम निर्भरता डिग्रेड है। Coordination API इस स्थिति में काम
करते रहने के लिए डिज़ाइन किया गया है — टेलीमेट्री इंजेशन एज पर लोकल बफ़र
करेगा और रिट्राई करेगा। आइडेम्पोटेंट क्लाइंट अनुरोधों को बैकऑफ के साथ
रिट्राई करना चाहिए।
त्रुटि की रिपोर्ट करना
यदि आप एक प्रजननीय विफलता का सामना करते हैं जो इस संदर्भ से मेल नहीं
खाती,
दस्तावेज़ रिपॉज़िटरी
पर एक issue खोलें और शामिल करें:
- HTTP विधि, पथ, और स्टेटस कोड
- Request ID (
X-Request-Id प्रतिक्रिया हेडर) यदि मौजूद हो
- अनुरोध बॉडी की संपादित कॉपी
- पूरी प्रतिक्रिया बॉडी