# Hata kodları

> YesCaptcha API'nin tüm hata kodlarının anlamı ve çözüm yolları: istek biçimi, hesap bakiyesi, eşzamanlı görev ve duraklatma, görev sonucu, site parametreleri, görsel, proxy, sunucu. Hata döndüren isteklerde puan düşülmez.

Source: https://docs.yescaptcha.com/tr/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

Bir istek hata verdiğinde API `errorId: 1` döndürür; `errorCode` hata kodu, `errorDescription` ise metin açıklamasıdır. Hata döndüren isteklerde puan düşülmez: görev oluşturulurken alınan hatalarda puan düşülmez, görev oluşturulduktan sonra tanıma başarısız olursa veya zaman aşımına uğrarsa puan iadesi otomatik yapılır.

> **İpucu:** Kodunuzda `errorDescription` metnine değil, `errorCode` değerine göre karar verin; metin açıklaması değişebilir.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## Hataları ele alma ilkeleri

1.  **Parametre hataları** (istek biçimi, ClientKey, görev türü, site parametreleri, görsel) isteği yeniden göndermekle değişmez; önce isteği düzeltin.
2.  **Tanıma hatası ve zaman aşımı** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) durumunda yeni bir görev oluşturabilirsiniz.
3.  Hatadan sonra bu `taskId` için **yoklamayı durdurun**; isteği aynen ve sık aralıklarla yeniden göndermeyin.
4.  “Otomatik duraklatmaya sayılır” olarak işaretlenen hatalardan aynı `clientKey` bir dakika içinde 100 tane alırsa görev oluşturma 5 dakika duraklatılır. “Önbellek” olarak işaretlenen hatalar bu sayıma girmez, ancak önbellek süresince aynı istek doğrudan aynı hatayı döndürür. Ayrıntılar için [Eşzamanlı görev sınırı ve otomatik duraklatma](https://docs.yescaptcha.com/tr/api/rate-limits.md) sayfasına bakın.

## Tüm hata kodları

### İstek biçimi

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Zorunlu bir alan eksik (ör. `clientKey` veya görev türü için gereken `websiteURL` / `websiteKey`) ya da istek gövdesi JSON değil | Görev türü sayfasında listelenen eksik alanları ekleyin; JSON'u `POST` ile ve `Content-Type: application/json` başlığıyla gönderin |
| `ERROR_REQUEST_FORMATS` (Duraklatmaya sayılır) | İstek gövdesi geçerli bir JSON değil | Gövdeyi metin birleştirme yerine bir JSON kütüphanesiyle oluşturun; JSON içinde `//` yorumları bulunmamalıdır |
| `ERROR_TASK_ABSENT` (Duraklatmaya sayılır) | `createTask` çağrısında `task` alanı eksik | Görev parametrelerini bir `task` nesnesine koyun. Python requests ile `json=data` kullanın, `data=data` kullanmayın |
| `ERROR_TASK_NOT_SUPPORTED` (Duraklatmaya sayılır) | `task.type` yanlış yazılmış ya da bu görev türü kaldırılmış | Tür adını "Görev türleri ve fiyatlar" sayfasından kopyalayın; adlar büyük/küçük harfe duyarlıdır |
| `ERROR_PAGE_NOT_FOUND` | İstenen yol mevcut değil | Uç nokta URL'sini kontrol edin, ör. `https://api.yescaptcha.com/createTask`; yöntem adları büyük/küçük harfe duyarlıdır |
| `ERROR_BAD_REQUEST` | İstek işlenemiyor; genellikle yanlış HTTP yöntemi (POST yerine GET) veya geçersiz parametre değerleri nedeniyle olur | JSON'u `POST` ile gönderin ve parametre türlerini ile değerlerini kontrol edin |
| `ERROR_ILLEGAL_PARAMETERS` | Bir parametre değeri geçersiz. Cloudflare doğrulama sayfasında sık görülür: `websiteURL` herkese açık bir `http://` / `https://` URL'si değil, `postData` bir nesne değil ya da `requiredCookies` bir dize dizisi değil (createTask tarafından döndürülür, puan düşülmez); veya hedef alan adı proxy üzerinden çözümlenemedi (getTaskResult tarafından döndürülür, puan otomatik olarak iade edilir) | Değeri görev türü sayfasındaki parametre tablosuna göre düzeltin. Alan adı çözümlenemediyse URL'nin yazımını ve proxy'nin siteye erişip erişemediğini kontrol edin |

### Hesap ve bakiye

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Duraklatmaya sayılır) | `clientKey` mevcut değil: kopyalarken karakter eklenmiş veya eksik kalmış ya da anahtar panelde sıfırlanmış | Anahtarı yescaptcha.com panelinden boşluk ve satır sonu olmadan yeniden kopyalayın |
| `ERROR_KEY_EXPIRED` (Duraklatmaya sayılır) | `clientKey` süresi doldu (createTask ve getBalance tarafından döndürülür, puan düşümü yapılmaz). İki durum söz konusudur: ya uzun süre kullanılmadığı için hesabı korumak amacıyla sistem bir son kullanma süresi belirlemiştir (süre dolmadan önce e-posta ile hatırlatma gönderilir) ya da bu `clientKey` için belirlenen son kullanma süresi geçmiştir | yescaptcha.com Paneline giriş yapın. Uzun süre kullanılmadığı için süresi dolduysa yeni bir `clientKey` oluşturun; Bakiye yeni `clientKey`'e otomatik olarak aktarılır. Bir son kullanma süresi belirlenmişse bu süreyi değiştirin veya başka bir `clientKey` kullanın. Ardından programınızı yeni `clientKey` ile güncelleyin |
| `ERROR_KEY_IP_NOT_ALLOWED` | Bu `clientKey` için bir IP izin listesi tanımlanmış ve isteğin geldiği IP bu listede yok (createTask ve getBalance tarafından döndürülür, puan düşümü yapılmaz, otomatik duraklatmaya sayılmaz) | yescaptcha.com Paneli'ne giriş yapın ve istekleri gönderen makinenin genel IP adresini bu `clientKey` için tanımlı izin listesine ekleyin ya da başka bir `clientKey` kullanın. API'yi birden fazla makineden çağırıyorsanız her makinenin genel IP adresini ekleyin (burada kastedilen, YesCaptcha API'sini çağıran IP'dir; görev parametrelerindeki proxy ile ilgisi yoktur) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Bu `clientKey` için bir harcama limiti tanımlanmış ve mevcut dönem için kalan limit bu görevin puan düşümünü karşılamıyor (createTask tarafından döndürülür, puan düşümü yapılmaz, otomatik duraklatmaya sayılmaz). Limit, fiilen düşülen puanları esas alır; başarısız olan veya zaman aşımına uğrayan görevler için iade edilen puanlar limite geri eklenir | yescaptcha.com Paneli'ne giriş yapıp bu `clientKey` için tanımlı limiti yükseltin, bir sonraki dönemi bekleyin (limit Pekin saatiyle her gün, her Pazartesi veya her ayın 1'inde sıfırlanır; tek seferlik limit sıfırlanmaz) ya da başka bir `clientKey` kullanın. `getBalance`, bu `clientKey` için kalan limiti döndürür (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Bakiye yetersiz. Görev oluşturmak için bakiyenin 10 puandan fazla olması gerekir | Bakiye yükleyip yeniden deneyin. Bakiyeyi kontrol etmek için `getBalance` kullanın |

### Eşzamanlı görev ve duraklatma

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Bazen duraklatmaya sayılır) | Hesapta bu türden çok fazla görev işleniyor. Yanıttaki `limit`, geçerli eşzamanlı görev sınırıdır. İstek işlenmedi ve puan düşülmedi | Devam eden isteklerin dönmesini bekleyin ya da 1–2 saniye bekleyip yeniden deneyin; aynı anda sonuç bekleyen istek sayısını sınırlayın |
| `ERROR_IP_BLOCKED_5MIN` | Bu `clientKey` kısa sürede çok fazla hata üretti ve otomatik olarak duraklatıldı. `retryAfter` kalan saniyedir, `blockReason` ise duraklatmaya neden olan hatadır | İsteği `blockReason` değerine göre düzeltin ve `retryAfter` saniye bekleyin; duraklatma sırasında istek göndermek süreyi uzatmaz |
| `ERROR_NO_SLOT_AVAILABLE` | Çözüm hizmeti geçici olarak aşırı yüklü. createTask tarafından döndürüldüğünde puan düşümü yapılmaz; kuyrukta çok uzun süre bekleyen bir görev için getTaskResult de bu hatayı döndürür ve puan iadesi otomatik olarak yapılır | Birkaç saniye bekleyin ve görevi yeniden oluşturun |

### Görevler ve sonuçlar

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Duraklatmaya sayılır) | `taskId` mevcut değil, süresi dolmuş (sonuçlar yaklaşık 10 dakika saklanır), başka bir `clientKey` değerine ait veya diğer uç noktada oluşturulmuş | Bu görevi yoklamayı bırakın. Görevi oluşturan uç nokta ve `clientKey` ile sorgulayın |
| `ERROR_TASK_TIMEOUT` | Görev süresi içinde tamamlanmadı (genellikle 110 saniye); puan iadesi otomatik olarak yapıldı | Yeni bir görev oluşturun; zaman aşımı devam ederse aynı CAPTCHA için başka bir görev türü deneyin |
| `ERROR_CAPTCHA_UNSOLVABLE` | CAPTCHA bu kez çözülemedi; puan iadesi yapıldı. Bu durum otomatik duraklatmaya sayılmaz | Yeni bir görev oluşturun. Hata devam ederse `websiteURL`, `websiteKey` ve diğer parametreleri kontrol edin veya aynı CAPTCHA için başka bir görev türü deneyin |
| `ERROR_SETTLEMENT_FAILED` (Duraklatmaya sayılır) | Hesaplaşma sırasında bakiye yetersizdi, bu nedenle sonuç döndürülmedi | Bakiye yükleyin ve yeni bir görev oluşturun |
| `ERROR_NO_SUCH_CAPCHA_ID` | Görev artık geçerli değil | Bu görevi yoklamayı bırakın ve yenisini oluşturun |
| `ERROR_RECAPTCHA_TIMEOUT` | CAPTCHA çözümü zaman aşımına uğradı; puan iadesi yapıldı | Yeni bir görev oluşturun |

### Hedef site parametreleri

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Önbelleğe alınır, duraklatmaya sayılmaz) | `websiteKey` geçersiz | Sitekey değerini sayfada yeniden bulun (parametre bulma kılavuzlarına bakın). Aynı istekler önbellek süresi boyunca bu hatayı doğrudan döndürür ve yanıtta `cached: true` bulunur |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Önbelleğe alınır, duraklatmaya sayılmaz) | `websiteURL` alan adı `websiteKey` ile eşleşmiyor | `websiteURL` değerini CAPTCHA'nın göründüğü sayfa olarak ayarlayın |
| `ERROR_INVALID_KEY_TYPE` (Önbelleğe alınır, duraklatmaya sayılmaz) | Sitekey farklı bir CAPTCHA'ya ait; örneğin v3 anahtarı bir v2 görev türüyle kullanılmış | Önce CAPTCHA'yı belirleyin ("CAPTCHA türünü belirleme" bölümüne bakın) ve uygun görev türünü seçin; görünmez v2 için `isInvisible` değerini ayarlayın |
| `ERROR_DOMAIN_NOT_ALLOWED` (Önbelleğe alınır, duraklatmaya sayılmaz) | Bu site desteklenmiyor | Aynı CAPTCHA için başka bir görev türünü deneyin veya Destek ile iletişime geçin |
| `ERROR_HIGH_DEMAND_DOMAIN` (Duraklatmaya sayılır) | Bu site desteklenmiyor | Bu site için görev göndermeyi bırakın ve Destek ile iletişime geçin |
| `ERROR_FAILED_LOADING_WIDGET` | CAPTCHA verilen parametrelerle yüklenemedi | `websiteURL` ve `websiteKey` değerlerini kontrol edin; kendi proxy'nizi kullanan görev türlerinde proxy'nin siteye erişebildiğinden emin olun |

### Görseller

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Duraklatmaya sayılır) | Görsel boş veya çok küçük | Base64 verisinin eksiksiz olduğunu ve `data:image/...;base64,` öneki içermediğini kontrol edin |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Duraklatmaya sayılır) | Görsel çok büyük | Görseli sıkıştırın veya küçültün; istek gövdesinin tamamı 6 MB'ın altında kalmalıdır |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Duraklatmaya sayılır) | Görsel biçimi desteklenmiyor veya görsel bu görev türünün işleyebileceği bir görsel değil. Tek bir oluşum bile anahtarı 30 dakika duraklatır | JPG veya PNG kullanın ve görselin görev türüyle uyumlu olduğundan emin olun; örneğin reCAPTCHA görsel tanıma için 100x100, 300x300 veya 450x450 gerekir |
| `ERROR_ILLEGAL_IMAGE` (Duraklatmaya sayılır) | Görsel boyutu bu görev türünün gereksinimlerini karşılamıyor | Görseli görev türü sayfasında açıklandığı gibi yeniden boyutlandırın |
| `ERROR_PARSE_IMAGE_FAIL` | Görsel çözümlenemedi; çoğunlukla Base64 eksik olduğundan veya bir önek içerdiğinden kaynaklanır | Base64 kodlamasını kontrol edin ve `data:` önekini ile satır sonlarını kaldırın |
| `ERROR_UNKNOWN_QUESTION` | `question` yanlış veya bu soru henüz desteklenmiyor | Görev türü sayfasındaki soru listesiyle karşılaştırın. Desteklenmeyen sorular için Destek ile iletişime geçin; yeni sorular genellikle 3 iş günü içinde desteklenir |
| `ERROR_UNKNOW_450x450_QUESTION` | Bu soru henüz 4x4 (450x450) görseller için desteklenmiyor | Başka bir soru almak için sayfadaki doğrulamayı yenileyin |

### Proxy'ler

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Proxy bağlantıyı reddetti | Proxy adresini, portunu ve protokolünü kontrol edin ve dış bağlantıları kabul ettiğinden emin olun (127.0.0.1 gibi yerel bir adres olmamalı) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Proxy'ye bağlanırken zaman aşımı oluştu | Daha güvenilir bir proxy kullanın |
| `ERROR_PROXY_READ_TIMEOUT` | Proxy üzerinden okuma sırasında zaman aşımı oluştu | Daha hızlı bir proxy kullanın |
| `ERROR_PROXY_BANNED` | Proxy kullanılamıyor veya IP adresi hedef site tarafından engellenmiş | Başka bir proxy kullanın |
| `ERROR_PROXY_INCORRECT` | Proxy parametreleri hatalı biçimlendirilmiş | `proxyType`, `proxyAddress`, `proxyPort` (veya `proxy` dizesi) biçimini kontrol edin |
| `ERROR_PROXY_TRANSPARENT` | Proxy şeffaf olduğundan gerçek IP adresini açığa çıkarıyor | Anonim (elite) bir proxy kullanın |
| `ERROR_PROXY_NOT_AUTHORISED` | Proxy kullanıcı adı veya şifresi yanlış | `proxyLogin` ve `proxyPassword` değerlerini (veya `proxy` dizesindeki kimlik bilgilerini) kontrol edin |
| `ERROR_PROXY_TLS_ERROR` | Proxy ile TLS el sıkışması başarısız oldu; çoğunlukla `proxyType` yanlış olduğu için olur (örneğin http proxy için https seçilmesi) | Proxy protokolünü kontrol edin |
| `ERROR_PROXY_CONNECTION_FAILED` | Proxy sunucusuna bağlanılamadı | Proxy adresini ve portunu kontrol edin ve proxy'nin çalıştığından emin olun |

### Sunucu

| Hata kodu | Anlamı | Ne yapmalı |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Hizmet geçici olarak kullanılamıyor (hata kodu `UNAVALIABLE` şeklinde yazılır) | Daha sonra yeniden deneyin; sorun devam ederse Destek ile iletişime geçin |
| `ERROR_INTERNAL_SERVER_ERROR` | Sunucu tarafında bir hata oluştu | Daha sonra yeniden deneyin; hata devam ederse `taskId` ile birlikte Destek ile iletişime geçin |
| `ERROR_UNKNOWN` | Sınıflandırılmamış bir hata | Daha sonra yeniden deneyin; hata devam ederse `taskId` ile birlikte Destek ile iletişime geçin |

## Ek alanlar

Bazı hataların yanıtında ek alanlar bulunur:

| Alan | Görüldüğü yer | Açıklama |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, önbelleğe alınmış hatalar | Kaç saniye daha beklenmesi gerektiği |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Duraklatmayı tetikleyen hata kodu |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Duraklatmayı tetikleyen isteklerin türü, URL’si ve sitekey değeri; sorunu bulmayı kolaylaştırır |
| `cached` | Önbelleğe alınmış hatalar | `true` ise bu sonuç önbellekten gelir, gerçek bir tanıma yapılmamıştır |
| `badRequest` | Önbelleğe alınmış hatalar | Önbellekle eşleşen parametreler |
| `limit` | `ERROR_THREADS_MAXIMUM` | Geçerli eşzamanlı görev üst sınırınız |

`errorDescription` metninin dil kuralları için [İstek ve yanıt](https://docs.yescaptcha.com/tr/api/overview.md) sayfasına bakın.