त्रुटियाँ और HTTP स्टेटस कोड
ऐप्लिकेशन की त्रुटियाँ application/problem+json (RFC 9457) इस्तेमाल करती हैं। पढ़ने लायक detail के बजाय स्थिर code और action के आधार पर कार्रवाई करें। सत्यापन त्रुटियों के errors में JSON Pointer स्थान होते हैं। सपोर्ट टीम से संपर्क करते समय request_id शामिल करें। प्रॉक्सी या ट्रांसपोर्ट की विफलताएँ अलग बॉडी लौटा सकती हैं, इसलिए JSON पार्स करने से पहले Content-Type देखें।
नीचे दिया गया काल्पनिक 422 उदाहरण बिलिंग से पहले अमान्य ईमेल सिंटैक्स दिखाता है। सार्वजनिक त्रुटि सूची में हर code, स्टेटस, व्याख्या और सुझाई गई कार्रवाई दी गई है।
| HTTP स्टेटस | आम तौर पर अर्थ | अगला कदम |
|---|---|---|
| 400 / 413 / 415 | गलत JSON, बहुत बड़ी बॉडी या असमर्थित मीडिया टाइप। | अनुरोध ठीक करें। |
| 401 / 403 | एक्सेस अस्वीकार, अकाउंट पर प्रतिबंध या पर्याप्त क्रेडिट नहीं। | code देखें; एक्सेस ठीक करें या क्रेडिट जोड़ें / ट्रायल रीसेट का इंतज़ार करें। |
| 422 | अमान्य इनपुट या असंगत विकल्प। | errors में बताए गए फ़ील्ड ठीक करें। |
| 404 / 405 | अज्ञात रूट या असमर्थित HTTP मेथड। | एंडपॉइंट पाथ और रिस्पॉन्स का Allow हेडर जाँचें। |
| 429 | अनुरोध दर या एक साथ चलने वाली प्रक्रियाओं की सीमा। | दूसरा अनुरोध भेजने से पहले Retry-After का इंतज़ार करें। |
| 500 | सर्वर की अनपेक्षित विफलता। | request_id के साथ सपोर्ट टीम से संपर्क करें; दोबारा प्रयास से पहले बिलिंग जाँचें। |
| 502 / 503 / 504 | सेवा प्रदाता, किसी निर्भर सेवा, बिलिंग या टाइमआउट की विफलता। | दोबारा प्रयास से पहले code, action और billing_status देखें। |
{
"type": "urn:genderapi:problem:validation_error",
"title": "validation error",
"status": 422,
"detail": "A valid email address is required.",
"instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
"code": "validation_error",
"request_id": "11111111-1111-4111-8111-111111111111",
"documentation": "https://api.genderapi.io/api/v2/errors",
"action": "correct_request",
"errors": [
{
"pointer": "/value",
"message": "Invalid email address."
}
],
"meta": {
"request_id": "11111111-1111-4111-8111-111111111111",
"duration_ms": 12,
"access": {
"mode": "ip_trial",
"reason": "api_key_missing"
},
"usage": {
"charged_credits": 0,
"remaining_credits": null,
"billing_status": "not_charged",
"resets_at": "2026-09-26T12:00:00.000Z",
"limit": 10,
"period_seconds": 86400
}
}
}त्रुटि रिस्पॉन्स के फ़ील्ड
| फ़ील्ड | प्रकार | Nullable | उदाहरण | विवरण |
|---|---|---|---|---|
type | string | नहीं | "urn:genderapi:problem:validation_error" | समस्या के प्रकार की पहचान करने वाला URI। |
title | string | नहीं | "validation error" | पढ़ने लायक त्रुटि का छोटा शीर्षक। |
status | integer | नहीं | 422 | HTTP स्टेटस कोड। |
detail | string | नहीं | "The request does not match the schema." | इस विशेष विफलता की व्याख्या। |
instance | string | नहीं | "urn:uuid:550e8400-e29b-41d4-a716-446655440000" | विफल अनुरोध का पहचानकर्ता। |
code | string | नहीं | "validation_error" | मशीन से पढ़ा जा सकने वाला स्थिर त्रुटि कोड। |
request_id | string | नहीं | "550e8400-e29b-41d4-a716-446655440000" | इस HTTP प्रयास का यूनिक पहचानकर्ता; X-Request-ID में भी भेजा जाता है। |
documentation | string | नहीं | "https://api.genderapi.io/api/v2/errors" | दिए जाने पर त्रुटि सूची का लिंक। |
action | string | नहीं | "correct_request" | सुझाई गई सुधार कार्रवाई; त्रुटि सूची में परिभाषित होने पर मौजूद। |
errors | array<object> | नहीं | [{"pointer":"/value","message":"must NOT have fewer than 1 characters"}] | सत्यापन की समस्याएँ, उपलब्ध होने पर। हर आइटम में pointer और message होते हैं। |
errors[].pointer | string | नहीं | "/value" | अमान्य इनपुट की पहचान करने वाला JSON Pointer। |
errors[].message | string | नहीं | "must NOT have fewer than 1 characters" | सत्यापन की समस्या की व्याख्या। |
एक्सेस, बिलिंग और अनुरोध का मेटाडेटा
| फ़ील्ड | प्रकार | Nullable | उदाहरण | विवरण |
|---|---|---|---|---|
meta.request_id | string | नहीं | "550e8400-e29b-41d4-a716-446655440000" | इस HTTP प्रयास का यूनिक पहचानकर्ता; X-Request-ID में भी भेजा जाता है। |
meta.duration_ms | integer | नहीं | 42 | मिलीसेकंड में अनुरोध प्रोसेस होने का समय। |
meta.access.mode | string | नहीं | "api_key" | api_key, ip_trial या unauthenticated। पेड अकाउंट इस्तेमाल करते समय api_key की पुष्टि करें। |
meta.access.reason | string | हाँ | null | IP ट्रायल पर जाने का कारण: api_key_missing, api_key_invalid या api_key_not_found; बाकी मामलों में null। |
meta.usage.charged_credits | integer | हाँ | 1 | कुल कटे हुए क्रेडिट। शुल्क लगने से पहले या पूरे रिफ़ंड की पुष्टि के बाद शून्य; बिलिंग की पुष्टि न होने पर null। |
meta.usage.remaining_credits | integer | हाँ | 99 | प्रक्रिया पूरी होने के समय का बैलेंस। नेगेटिव हो सकता है; उपलब्ध न होने या बिलिंग की पुष्टि न होने पर null। |
meta.usage.billing_status | string | नहीं | "confirmed" | not_charged, confirmed या unconfirmed। विफल अनुमान का दोबारा प्रयास करने से पहले इसे जाँचें। |
meta.usage.resets_at | string | हाँ | "2026-09-27T12:00:00.000Z" | UTC में IP ट्रायल रीसेट होने का समय (ISO 8601); API कुंजी वाले अकाउंट के लिए या पता न होने पर null। |
meta.usage.limit | integer | हाँ | 10 | IP ट्रायल की सीमा; API कुंजी वाले अकाउंट के लिए null। |
meta.usage.period_seconds | integer | हाँ | 86400 | सेकंड में IP ट्रायल की अवधि; API कुंजी वाले अकाउंट के लिए null। |
दोबारा प्रयास और बिलिंग
अनुमान का हर अनुरोध एक नई प्रक्रिया है, वही अनुरोध दोबारा भेजने पर भी। हर अनुरोध पर क्रेडिट के सामान्य नियम लागू होते हैं। डुप्लिकेट अनुरोधों से कोई सुरक्षा नहीं है, इसलिए कनेक्शन टूटने या परिणाम पता न होने पर अपने-आप दोबारा प्रयास न करें।
429 रिस्पॉन्स पर दूसरा अनुरोध भेजने से पहले Retry-After का इंतज़ार करें। अनुमान की विफलताओं में पहले code, action और meta.usage.billing_status देखें। billing_reconciliation_required या बिलिंग की पुष्टि न होने पर दोबारा प्रयास से पहले request_id के साथ सपोर्ट टीम से संपर्क करें।
आंशिक रूप से सफल बैच HTTP 200 लौटा सकता है। हर आइटम जाँचें और बिलिंग की पुष्टि के बाद सिर्फ़ विफल आइटम दोबारा भेजें; सफल आइटम दोबारा भेजने पर उन पर फिर से शुल्क लगेगा।
X-Request-ID और meta.request_id मौजूदा HTTP प्रयास की पहचान करते हैं। मौजूदा बैलेंस के लिए /usage पढ़ें। HEAD से शुल्क वाला अनुमान शुरू नहीं होता। अनुमान और अकाउंट के रिस्पॉन्स कैश नहीं किए जा सकते।
क्लाइंट को रिस्पॉन्स में जोड़े गए नए फ़ील्ड स्वीकार करने चाहिए और जानकारी उपलब्ध न होने पर null मान वैसे ही रखने चाहिए।
अनुरोध की सीमाएँ
यह मानने के बजाय कि इन सीमाओं तक अनुरोध हमेशा स्वीकार होंगे, HTTP 429 और Retry-After को संभालें। सेवा की क्षमता साझा होती है। दिखाए गए मान सेवा के मौजूदा डिफ़ॉल्ट हैं। अनुरोध दर की सीमा वाले रिस्पॉन्स में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset (Unix सेकंड) होते हैं। Retry-After सेकंड में इंतज़ार का समय है। ये हेडर अनुरोध की सीमाएँ बताते हैं, बचे हुए क्रेडिट नहीं। मुफ़्त /usage अनुरोध भी अनुरोध दर की सीमा में गिना जाता है।
| सीमा | मान |
|---|---|
| JSON अनुरोध बॉडी | अधिकतम 64 KiB |
| अनुमान के लिए मान | 1–254 अक्षर |
| बैच अनुरोध | API कुंजी के साथ 50 आइटम; IP ट्रायल में 10 |
| अकाउंट के लिए अनुरोध दर | प्रति मिनट 120 अनुरोध |
| IP के लिए अनुरोध दर | प्रति मिनट 600 अनुरोध |
| एक साथ चलने वाली प्रक्रियाएँ | हर अकाउंट के लिए 2; पूरी सेवा में 16 |