أخطاء API 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
    }
  }
}

• كتالوج أخطاء الإصدار الثاني الكامل

إعادة المحاولة وإعداد الفواتير

كل طلب تنبؤ هو عملية جديدة، بما في ذلك طلب مماثل تم إرساله مرة أخرى. تنطبق قواعد الائتمان العادية على كل طلب. لا توجد حماية للطلبات المكررة، لذا تجنب إعادة المحاولة التلقائية بعد فقدان الاتصال أو نتيجة غير معروفة.

للحصول على رد 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 المجانية يتم احتسابها ضمن حدود المعدل.