GenderAPI.io V2: الأخطاء والحدود وإعادة المحاولة

الأخطاء ورموز حالة HTTP

تستخدم أخطاء التطبيق application/problem+json (RFC 9457). ابنِ منطقك على الحقلين الثابتين code وaction، لا على النص المقروء في detail. في أخطاء التحقق، يحتوي errors على مؤشرات JSON Pointer للحقول المعنية. اذكر request_id عند التواصل مع فريق الدعم. عند أعطال الوكيل أو النقل قد يختلف جسم الاستجابة، لذا تحقّق من Content-Type قبل تحليل JSON.

يوضّح مثال 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 (بثواني Unix). وقيمة Retry-After مدة انتظار بالثواني. تصف هذه الترويسات حدود الطلبات، لا الأرصدة المتبقية. حتى قراءة /usage المجانية تُحتسب ضمن حدود معدل الطلبات.