API V2 hatalar ve yeniden denemeler

Hatalar ve HTTP durum kodları

Uygulama hataları application/problem+json (RFC 9457) kullanır. Kararlarınızı açıklama metni detail yerine sabit code ve action alanlarına dayandırın. Doğrulama hataları errors içinde JSON Pointer konumları içerir. Desteğe request_id iletin. Proxy veya aktarım hatalarında gövde farklı olabileceğinden JSON ayrıştırmadan önce Content-Type kontrol edin.

Aşağıdaki temsili 422 yanıtı, ücretlendirmeden önce reddedilen geçersiz e-posta sözdizimini gösterir. Genel hata kataloğu tüm kodları, durumları, açıklamaları ve önerilen eylemleri listeler.

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

• Tam V2 hata kataloğu

Yeniden denemeler ve ücretlendirme

Aynı isteğin tekrar gönderilmesi dahil her tahmin yeni işlemdir. Her istekte normal kredi kuralları geçerlidir. Yinelenen istek koruması yoktur; bağlantı kaybı veya sonucu bilinmeyen işlem sonrasında otomatik yeniden denemeden kaçının.

429 yanıtında Retry-After süresini bekleyin. Tahmin hatalarında önce code, action ve meta.usage.billing_status alanlarını inceleyin. billing_reconciliation_required veya unconfirmed ücretlendirmede yeniden denemeden önce request_id ile destek alın.

Kısmen başarılı toplu sorgu HTTP 200 dönebilir. Her öğeyi kontrol edin; ücretlendirme doğrulandıktan sonra yalnızca başarısız öğeleri yeniden gönderin. Başarılı öğeler tekrar gönderilirse yeniden ücretlendirilir.

X-Request-ID ve meta.request_id, o HTTP denemesini tanımlar. Güncel bakiye için /usage kullanın. HEAD, ücretli tahmin başlatmaz. Tahmin ve hesap yanıtları önbelleğe alınamaz.

İstemciler yeni yanıt alanlarına tolerans göstermeli, bilgi bulunmadığında null değerlerini korumalıdır.

İstek sınırları

Bu üst sınırlarda her isteğin kabul edileceğini varsaymayın; HTTP 429 ve Retry-After durumlarını işleyin. Kapasite ortaktır ve değerler mevcut hizmet varsayılanlarıdır. Hız sınırı yanıtlarında X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset (Unix saniyesi) bulunur. Retry-After saniye cinsinden bekleme süresidir. Bu başlıklar krediyi değil istek sınırlarını gösterir. Ücretsiz /usage da hız sınırına dahildir.