API v2 त्रुटियाँ और पुनः प्रयास

त्रुटियाँ और HTTP स्थिति कोड

एप्लिकेशन त्रुटियाँ application/problem+json (RFC 9457) का उपयोग करती हैं। detail में व्याख्यात्मक पाठ के बजाय स्थिर फ़ील्ड code और action का उपयोग करके त्रुटियों को संभालें। सत्यापन त्रुटियों के लिए, errors में प्रभावित फ़ील्ड के लिए JSON पॉइंटर स्थान शामिल हैं। समर्थन से संपर्क करते समय request_id शामिल करें। प्रॉक्सी या कनेक्शन विफलता एक अलग प्रतिक्रिया निकाय लौटा सकती है; JSON को पार्स करने से पहले सामग्री-प्रकार की जाँच करें। (Content-Type).

निम्नलिखित सिंथेटिक 422 उदाहरण बिलिंग से पहले अमान्य ईमेल सिंटैक्स दिखाता है। सार्वजनिक त्रुटि कैटलॉग प्रत्येक कोड, स्थिति, स्पष्टीकरण और सुझाई गई कार्रवाई को सूचीबद्ध करता है।

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

• पूर्ण v2 त्रुटि सूची

पुन: प्रयास करें और बिलिंग करें

प्रत्येक पूर्वानुमान अनुरोध एक नया ऑपरेशन है, जिसमें दोबारा भेजा गया एक समान अनुरोध भी शामिल है। प्रत्येक अनुरोध पर सामान्य क्रेडिट नियम लागू होते हैं। कोई डुप्लिकेट-अनुरोध सुरक्षा नहीं है, इसलिए कनेक्शन हानि या अज्ञात परिणाम के बाद स्वचालित पुनः प्रयास से बचें।

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 (यूनिक्स सेकंड) शामिल हैं। Retry-After सेकंड में देरी है। ये हेडर अनुरोध सीमा का वर्णन करते हैं, शेष क्रेडिट का नहीं। यहां तक कि मुफ़्त /usage रीड को भी दर सीमा में गिना जाता है।