API Status Kodları

Bu sayfa, doküman içinde geçen API’ler için HTTP status kodlarını ve pratik yorumlarını toplar.

Status Code	Anlam	Açıklama (Ne zaman döner / ne demektir / geliştirici ne yapmalı)
200	OK	Başarılı yanıt. İstek sorunsuz işlendi ve response body beklenen veriyi içerir (ör. Assistant/Workflow çıktısı, liste, detay). Kullanıcı: Response şemasını doğrulayın; beklenen alanları kontrol edin.
204	No Content	Başarılı ama içerik yok. Genelde silme/iptal işlemleri veya “başarıyla güncellendi ama dönecek veri yok” senaryolarında döner. Kullanıcı: Body beklemeyin; UI/akışta başarı durumunu buna göre işleyin.
400	Bad Request	Geçersiz istek. Hatalı JSON, eksik zorunlu alan, yanlış tip/format, hatalı query parametreleri, tutarsız alan kombinasyonları gibi durumlarda döner. Kullanıcı: İstek payload’ını ve parametreleri düzeltin; dönen hata detaylarını (alan bazlı mesajlar) kullanıcıya net yansıtın.
401	Unauthorized	Kimlik doğrulama eksik/yanlış. Token yok, geçersiz veya süresi dolmuş olabilir. Kullanıcı: Authorization header’ını kontrol edin; token yenileyin/yeniden oturum açtırın; doğru ortam (env) için doğru anahtar/token kullandığınızdan emin olun.
403	Forbidden	Yetki yok. Kimlik doğrulama başarılı olsa da bu kaynağa/işleme erişim izniniz yok (rol/scope/tenant kısıtı). Kullanıcı: Doğru rol/scope ile deneyin; proje/organizasyon izinlerini kontrol edin; bu endpoint’in gerektirdiği yetkileri dokümana göre eşleştirin.
404	Not Found	Kaynak veya endpoint bulunamadı. Yanlış URL/route, hatalı ID, yanlış base URL veya yanlış environment kullanımında görülebilir. Kullanıcı: Endpoint path’ini, resource ID’yi ve base URL’i kontrol edin; kaynağın gerçekten oluşturulduğundan emin olun.
405	Method Not Allowed	HTTP metodu desteklenmiyor. Endpoint var ama kullanılan metod yanlış (örn. GET yerine POST). Kullanıcı: Doğru metodu kullanın; client/SDK çağrısında endpoint-metod eşleşmesini kontrol edin (gerekirse Allow header’ına bakın).
406	Not Acceptable	İstenen response formatı üretilemiyor. İstemcinin Accept header’ı desteklenmeyen bir format istiyor olabilir. Kullanıcı: Genellikle Accept: application/json kullanın; content-negotiation ayarlarınızı düzeltin.
408	Request Timeout	Zaman aşımı. Sunucu belirli bir süre içinde isteğin tamamını alamadı / işlemeye başlayamadı (yavaş ağ, uzun süren istek, upload gecikmesi vb.). Kullanıcı: Timeout ayarlarını gözden geçirin; isteği yeniden deneyin; payload’ı küçültün veya işlemi parçalara bölün; uzun işlemler için platformun önerdiği asenkron modeli (job/polling) varsa onu tercih edin.
413	Payload Too Large	İstek gövdesi çok büyük. Büyük dosya/JSON gönderimi limitleri aştığında döner. Kullanıcı: Payload’ı küçültün; dosyayı bölerek gönderin (chunk/multipart); limitleri kontrol edin ve upload için önerilen yöntemi kullanın.
415	Unsupported Media Type	Yanlış Content-Type. Sunucu beklenen formatta veri alamıyor (örn. JSON beklerken farklı content-type). Kullanıcı: Content-Type: application/json (veya dokümanda belirtileni) kullanın; body formatının header ile uyumlu olduğundan emin olun.
429	Too Many Requests	Rate limit/kota aşıldı. Çok sık istek veya plan limitleri nedeniyle istekler kısıtlanır. Kullanıcı: Retry-After varsa ona uyun; exponential backoff ile retry uygulayın; istekleri throttle edin, batch/caching kullanın; gerekirse plan/kota artırın.
431	Request Header Fields Too Large	Header’lar çok büyük. Çok büyük cookie, uzun token, şişmiş custom header’lar nedeniyle döner. Kullanıcı: Header boyutlarını azaltın; cookie temizleyin; gereksiz header’ları kaldırın; büyük veriyi header yerine body veya sunucu tarafı state ile taşıyın.
499	Client Closed Request (İstemci isteği kapattı)	İstemci (uygulama, tarayıcı, gateway/proxy) yanıt gelmeden bağlantıyı kapattığında görülür. Genellikle kullanıcı sayfadan çıktı, istek iptal edildi, istemci timeout’a düştü veya bağlantı koptu. Kullanıcı: İstemci timeout değerlerini kontrol edin; uzun süren işlemler için asenkron model (job/polling) kullanın; isteği idempotent tasarlayıp güvenli retry uygulayın; ağ kopmalarına karşı tekrar deneme/backoff ekleyin; mümkünse isteği küçültün ve loglarda “client cancelled/aborted” gibi kayıtlarla eşleştirin.
500	Internal Server Error	Sunucuda beklenmeyen hata. Çoğunlukla yakalanmamış exception, yanlış konfigürasyon, bağımlılık hatası. Kullanıcı: İstek ID/trace ID varsa loglarla eşleştirin; aynı isteği kontrollü şekilde tekrar deneyin; kalıcıysa destek ekibine hata detaylarıyla iletin.
503	Service Unavailable	Servis geçici olarak kullanılamıyor. Bakım, aşırı yük veya bağımlı servis sorunları (downstream) olabilir. Kullanıcı: Kısa süre sonra retry/backoff uygulayın; kritik akışlarda fallback/graceful degradation ekleyin; status/health sayfası varsa kontrol edin.
504	Gateway Timeout	API isteği işlerken arka taraftaki bağımlı bir servisten (örn. workflow runner, connector, storage, provider) zamanında yanıt alamadığında döner. Genelde geçici yoğunluk/ağ gecikmesi kaynaklıdır. Kullanıcı: İsteği retry edin (exponential backoff önerilir), timeout değerlerinizi kontrol edin; uzun süren işler için mümkünse asenkron/polling yaklaşımı kullanın.