> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/tr/docs/error-codes

# Hata kodları

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

### 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.

```json
{
  "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 `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.
