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ı
| Alan | Açıklama |
|---|---|
code | Makinelerin okuyabileceği kararlı hata kodu. Kodlar asla yeniden adlandırılmaz, bu nedenle koşul dallarında güvenle kullanabilirsiniz. |
message | Hatanın okunabilir açıklaması. İfade değişebilir, bu yüzden ayrıştırmayın. |
type | validation_error, authentication_error veya rate_limit_error gibi genel hata kategorisi. |
status | Günlükler ve kuyruklar için yanıt gövdesinde de tekrarlanan HTTP durum kodu. |
retryable | Aynı isteğin daha sonra yeniden denendiğinde başarılı olup olamayacağını belirtir. |
request_id | Benzersiz istek tanımlayıcısı. X-Request-Id başlığıyla eşleşir. |
docs_url | Bu 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_after | Yeniden 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.
| Kod | HTTP durumu | Tür | Yeniden denenebilir | Açı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
retryabledeğeritrueolduğunda yeniden deneyin. Doğrulama, kimlik doğrulama ve yetki hatalarında önce isteği düzeltin. retry_afterveyaRetry-Afterbaş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-Keybaş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.