Geliştirici referansı

Hata kodları

Hata kodları API belgelerini, istek parametrelerini, yanıt alanlarını, kod örneklerini ve DomScan entegrasyonları için hata işlemeyi inceleyin.

Hata kodları

Yapılandırılmış hatalar

Her API hatası aynı JSON yapısını döndürür: kararlı bir code, okunabilir bir message, type ve HTTP status değeri, retryable bilgisi, request_id ve docs_url içeren bir error nesnesi. request_id her zaman X-Request-Id yanıt başlığıyla eşleşir; destekle iletişime geçerken bunu belirtin.

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Geçersiz alan adı biçimi",
    "suggestion": "example.com gibi kaydedilebilir bir alan adı kullanın",
    "type": "validation_error",
    "status": 400,
    "retryable": false,
    "request_id": "m5x7k2p-a9f3",
    "docs_url": "https://domscan.net/docs/check-availability"
  }
}

Hata alanları

AlanAçıklama
codeMakinelerin okuyabileceği kararlı hata kodu. Kodlar asla yeniden adlandırılmaz, bu nedenle koşul dallarında güvenle kullanabilirsiniz.
messageHatanın okunabilir açıklaması. İfade değişebilir, bu yüzden ayrıştırmayın.
typevalidation_error, authentication_error veya rate_limit_error gibi genel hata kategorisi.
statusGünlükler ve kuyruklar için yanıt gövdesinde de tekrarlanan HTTP durum kodu.
retryableAynı isteğin daha sonra yeniden denendiğinde başarılı olup olamayacağını belirtir.
request_idBenzersiz istek tanımlayıcısı. X-Request-Id başlığıyla eşleşir.
docs_urlBu hatayı açıklayan belge bölümünün bağlantısı.
suggestionİsteğin nasıl düzeltileceğine dair isteğe bağlı ipucu.
detailsİzin verilen yöntemler veya geçersiz parametre gibi isteğe bağlı yapılandırılmış bağlam.
retry_afterYeniden denemeden önce beklenecek saniye sayısı (isteğe bağlı). Ayrıca Retry-After başlığı olarak da gönderilir.

Yaygın hata kodları

Bunlar çoğu istemcinin ele alması gereken kodlardır. Bazı uç noktalar aynı kuralları izleyen daha özel kodlar döndürür; durum, tür ve yeniden deneme davranışıyla birlikte tam liste OpenAPI belirtiminde x-domscan-error-codes altında yer alır. RATE_LIMIT_EXCEEDED, RATE_LIMITED için takma ad olarak hâlâ kabul edilir.

KodHTTP durumuTürYeniden denenebilirAçıklama
BAD_REQUEST 400 validation_error Hayir Eksik veya geçersiz parametreler
MISSING_PARAMETER 400 validation_error Hayir Gerekli bir parametre eksik
INVALID_PARAMETER 400 validation_error Hayir Bir parametrenin değeri geçersiz
INVALID_JSON 400 validation_error Hayir İstek gövdesi geçerli bir JSON değil
INVALID_DOMAIN 400 validation_error Hayir Geçersiz alan adı biçimi
UNSUPPORTED_TLD 400 validation_error Hayir TLD desteklenmiyor
SUBDOMAIN_NOT_SUPPORTED 400 validation_error Hayir Bu uç nokta alt alan adlarını değil, kaydedilebilir alan adlarını kabul eder
VALIDATION_ERROR 422 validation_error Hayir İstek doğru biçimlendirilmiş ancak işlenemiyor
AUTH_REQUIRED 401 authentication_error Hayir API anahtarı veya oturum sağlanmadı
INVALID_API_KEY 401 authentication_error Hayir API anahtarı geçersiz veya iptal edilmiş
INSUFFICIENT_CREDITS 402 credits_error Hayir Hesabınızda bu istek için yeterli kredi yok
FORBIDDEN 403 permission_error Hayir Bu işlem için yetkiniz yok
NOT_FOUND 404 not_found_error Hayir Uç nokta veya kaynak mevcut değil
METHOD_NOT_ALLOWED 405 request_error Hayir Uç nokta mevcut ancak bu HTTP yöntemini kabul etmiyor. Allow başlığı desteklenen yöntemleri listeler.
CONFLICT 409 conflict_error Hayir İstek, kaynağın mevcut durumuyla çakışıyor
IDEMPOTENCY_CONFLICT 409 conflict_error Hayir Idempotency anahtarı daha önce farklı bir istekle kullanılmış
IDEMPOTENCY_KEY_REUSED 422 validation_error Hayir Bu Idempotency-Key son 24 saat içinde farklı bir istekle kullanıldı. Yeni bir istek için yeni bir anahtar kullanın.
IDEMPOTENCY_IN_PROGRESS 409 conflict_error Evet Bu Idempotency-Key ile gönderilen bir istek hâlâ çalışıyor. Saklanan yanıtı almak için kısa süre sonra yeniden deneyin.
RATE_LIMITED 429 rate_limit_error Evet Çok fazla istek
INTERNAL 500 api_error Hayir Beklenmeyen sunucu hatası. Devam ederse istek kimliğiyle birlikte destekle iletişime geçin.
UPSTREAM_ERROR 502 upstream_error Evet Bir üst kaynak kullanılamaz bir yanıt döndürdü
UPSTREAM_UNAVAILABLE 503 upstream_error Evet Bir üst kaynak geçici olarak kullanılamıyor
SERVICE_UNAVAILABLE 503 upstream_error Evet Hizmet geçici olarak kullanılamıyor
TIMEOUT 504 timeout_error Evet Bir üst kaynak veya kayıt kuruluşu zamanında yanıt vermedi

Yeniden deneme rehberi

  • Yalnızca retryable değeri true olduğunda yeniden deneyin. Doğrulama, kimlik doğrulama ve yetki hatalarında önce isteği düzeltin.
  • retry_after veya Retry-After başlığı varsa, bir sonraki denemeden önce en az o kadar saniye bekleyin.
  • Aksi halde rastgele sapmalı üstel geri çekilme kullanın, örneğin 1, 2, 4 ve 8 saniye, ve birkaç denemeden sonra durun.
  • Toplu işlem ve iş oluştururken Idempotency-Key başlığını gönderin; böylece yeniden gönderilen istek yinelenen bir iş oluşturmaz.
  • Kredi düşen diğer POST isteklerinde Idempotency-Key üst bilgisi, yeniden denemenin tekrar ücret almak yerine saklanan yanıtı döndürmesini sağlar.

Uyumluluk

10 Ekim 2026 itibarıyla tüm uç noktalar bu biçimi kullanıyor. Bazı uç noktaların zaten döndürdüğü credits_remaining, purchase_url, login_url, success veya meta gibi alanlar bir uyumluluk döneminde korunur, böylece mevcut entegrasyonlar çalışmaya devam eder. Yeni kodda hata ayrıntılarını error nesnesinden okuyun.