Hatalar

Hata yanıtının biçimi, bütün hata kodları, hangisinin yeniden denenebileceği ve her birinde ne yapılacağı.

Hatalar OpenAI'nin hata biçimiyle gelir. OpenAI SDK'ları onları kendi hata sınıflarına çevirir.

{
  "error": {
    "message": "Bu tarayıcı anahtarı bu sitede kullanılamaz. Siteyi anahtarın izinli siteleri arasına ekleyin.",
    "type": "permission_error",
    "param": null,
    "code": "origin_not_allowed"
  }
}

message Türkçedir ve son kullanıcıya gösterilebilecek kadar sadedir.
code İngilizcedir ve değişmez. Kodunuzda her zaman code'a bakın, message'a değil.
param hatayı doğuran alanın adıdır, örneğin model, messages, input ya da after. İlgili bir alan yoksa null olur.

POST /chat bu kuralın tek istisnasıdır. Orada gövde JSON değil, düz metindir: message'daki Türkçe metnin kendisi. Vercel AI SDK bu metni olduğu gibi useChat'in error.message değerine koyar. Kod X-Sone-Error-Code başlığında gelir; bu başlık tarayıcıdaki koda açılmaz, yalnız sunucudan yapılan isteklerde okunur.

Kodlar

x-should-retry sütununda false olan hatalarda aynı isteği yeniden göndermeyin. Retry-After sütunu, başlığın taşıdığı bekleme süresidir.

Durum	`code`	`x-should-retry`	`Retry-After`	Anlamı ve ne yapmalı
`400`	`invalid_body`	yok	yok	Gövde boş ya da okunamadı. İsteği JSON gövdeyle gönderin.
`400`	`invalid_json`	yok	yok	Gövde geçerli JSON değil ya da bir alanın türü yanlış. `message` ayrıntıyı verir.
`400`	`missing_user_message`	yok	yok	Son mesaj metin taşıyan bir `user` mesajı değil. Ziyaretçinin yeni mesajını sona koyun.
`400`	`invalid_role`	yok	yok	Tanınmayan bir mesaj rolü ya da Responses'ta rolü olmayan bir mesaj öğesi.
`400`	`invalid_content`	yok	yok	Bir mesajın içeriği metin ya da parça dizisi değil.
`400`	`unsupported_content`	yok	yok	Yeni mesajda görsel, ses ya da dosya var. Yalnız metin gönderin.
`400`	`message_too_long`	yok	yok	Yeni bir mesaj 4.000 karakterden uzun. Mesajı kısaltın.
`400`	`too_many_new_messages`	yok	yok	Tek istekte 12'den fazla yeni ziyaretçi mesajı var. Asistanın yanıtını geçmişe ekleyip devam edin ya da yeni sohbet başlatın.
`400`	`tools_not_supported`	yok	yok	`tools`, `functions` ya da işlev çağrısı öğeleri gönderildi. Asistan işletmenin kendi araçlarını kullanır; bu alanları çıkarın.
`400`	`unsupported_parameter`	yok	yok	`n` 1 dışında, `response_format` ya da `text.format` `text` dışında ya da `background: true`. `param` alanın adını verir.
`400`	`missing_input`	yok	yok	Responses isteğinde `input` yok.
`400`	`invalid_input`	yok	yok	Responses isteğinde `input` bir metin ya da öğe dizisi değil.
`400`	`unsupported_item`	yok	yok	Responses isteğinde tanınmayan bir girdi öğesi türü var.
`400`	`conflicting_parameters`	yok	yok	`previous_response_id` ile `conversation` birlikte gönderildi. Birini bırakın.
`400`	`instructions_too_long`	yok	yok	Responses isteğinde `instructions` 2.000 karakterden ya da JSON olarak 4 KB'tan uzun.
`400`	`invalid_metadata`	yok	yok	Responses isteğinde `metadata` sınırı aşıyor: en fazla 16 anahtar, anahtar en fazla 64 karakter, değer en fazla 512 karakterlik metin, tamamı JSON olarak en fazla 4 KB.
`400`	`safety_identifier_too_long`	yok	yok	Responses isteğinde `safety_identifier` 64 karakterden uzun.
`400`	`user_too_long`	yok	yok	Responses isteğinde `user` 64 karakterden uzun.
`400`	`previous_response_id_too_long`	yok	yok	`previous_response_id`, boşlukları atıldıktan sonra bir yanıt kimliğinden uzun. Yanıtın `id` değerini olduğu gibi gönderin.
`400`	`item_id_too_long`	yok	yok	Responses isteğinde bir `item_reference` kimliği 64 karakterden uzun.
`400`	`conversation_model_mismatch`	`false`	yok	Sohbet başka bir asistanla açılmış. Aynı `model` ile sürdürün ya da yeni sohbet başlatın.
`400`	`conversation_full`	`false`	yok	Sohbette 200 ziyaretçi mesajına ulaşıldı. Yeni sohbet başlatın.
`400`	`invalid_cursor`	yok	yok	`after` bu sohbete ait bir mesajın kimliği değil. İmleci bırakıp sohbeti baştan okuyun.
`400`	`not_cancellable`	yok	yok	`POST /responses/{id}/cancel` çağrıldı. Yanıtlar istek içinde tamamlanır, iptal edilecek iş yoktur.
`401`	`missing_api_key`	yok	yok	Anahtar gönderilmedi.
`401`	`invalid_api_key`	yok	yok	Anahtar tanınmadı, biçimi bozuk ya da öneki türüyle uyuşmuyor.
`401`	`revoked_api_key`	yok	yok	Anahtar iptal edilmiş. Yenisini oluşturun.
`402`	`plan_required`	`false`	yok	Çalışma alanının paketi asistan yanıtlarına açık değil. Asistan yanıt vermedi.
`403`	`origin_not_allowed`	yok	yok	Tarayıcı anahtarı izin verilen siteler dışından ya da `Origin` başlığı olmadan kullanıldı. Siteyi anahtara ekleyin.
`403`	`secret_key_in_browser`	yok	yok	Sunucu anahtarı bir tarayıcıdan kullanıldı. Tarayıcıda tarayıcı anahtarı kullanın.
`404`	`model_not_found`	yok	yok	Bu kimlikte, anahtarın çağırabildiği yayında bir asistan yok. `GET /models` kullanılabilenleri listeler.
`404`	`conversation_not_found`	yok	yok	Sohbet bu çalışma alanında bir API sohbeti değil ya da anahtarınızın çağıramadığı bir asistanın. Sakladığınız kimliği bırakıp yeni sohbet başlatın.
`404`	`previous_response_not_found`	yok	yok	`previous_response_id` ile gösterilen yanıt yok, silinmiş, `store: false` ile üretilmiş ya da anahtarınızın çağıramadığı bir asistanın sohbetinde.
`404`	`response_not_found`	yok	yok	Saklanan yanıt yok, silinmiş, 30 günü geçmiş ya da anahtarınızın çağıramadığı bir asistanın sohbetinde. `DELETE /responses/{id}`'de ayrıca: yanıtı başka bir anahtar saklamış.
`404`	`file_not_found`	yok	yok	Dosya bağlantısının süresi dolmuş ya da bağlantı bozuk. Sohbetin mesajlarını yeniden okuyup yeni bağlantıyı alın.
`409`	`conversation_busy`	yok	2	Aynı sohbette önceki mesaj hâlâ yanıtlanıyor; bu mesaj kaydedilmedi. Bekleyip aynı `Idempotency-Key` ile yeniden gönderin.
`413`	`request_too_large`	yok	yok	Gövde 1 MB'den büyük. Bütün geçmiş yerine sohbet kimliğini gönderin.
`422`	`idempotency_key_reused`	`false`	yok	Aynı `Idempotency-Key` başka bir metinle gönderildi. Her yeni mesajda yeni bir anahtar kullanın.
`429`	`rate_limit_exceeded`	yok	Pencereye göre	Anahtarın istek ya da okuma sınırı aşıldı. `Retry-After` kadar bekleyin.
`429`	`ai_turn_ceiling`	`false`	300	Çalışma alanının API için saatlik ya da günlük otomatik yanıt sınırı, tarayıcı anahtarıyla gelen istekte tarayıcı anahtarlarının payı doldu. Asistan yanıt vermedi.
`429`	`assistant_quota_exhausted`	`false`	yok	Sonecentral'ın yapay zekâ kapasitesi şu an dolu. Çalışma alanınızın bir hakkı bitmiş değildir; API yanıtları paketinizden düşmez. Asistan yanıt vermedi: `message` "Asistan şu an yanıt veremiyor." der.
`429`	`file_download_limit`	yok	Pencereye göre	Aynı dosya kimliği son bir saatte 10 kez indirildi. `Retry-After` kadar bekleyin.
`429`	`file_egress_limit`	yok	UTC gece yarısına kadar	Çalışma alanının günlük dosya indirme sınırı doldu.
`503`	`assistant_paused`	Mesaj ekibe ulaştıysa `false`	60	Otomatik yanıtlar şu an kapalı. Asistan yanıt vermedi.
`503`	`assistant_unavailable`	yok	30	Asistan şu an yanıt veremiyor. Bekleyip aynı `Idempotency-Key` ile yeniden gönderin.
`503`	`conversation_not_created`	yok	yok	Sohbet açılamadı. Biraz sonra yeniden deneyin.
`503`	`message_not_stored`	yok	yok	Mesaj kaydedilemedi. Aynı `Idempotency-Key` ile yeniden deneyin.
`503`	`messages_unavailable`	yok	yok	Sohbetin mesajları şu an okunamadı. Sonraki okumada yeniden deneyin.
`503`	`file_unavailable`	yok	yok	Dosya şu an indirilemiyor. Biraz sonra yeniden deneyin.
`503`	`response_not_deleted`	yok	yok	Saklanan yanıt şu an silinemedi. Biraz sonra yeniden deneyin.

Retry-After saniye cinsindendir ve yukarı yuvarlanır.

Bu kodların dışında iki durum vardır. Aynı adresten dakikada 120'den fazla dosya indirme isteği 429 alır ve bu yanıtın gövdesi OpenAI biçiminde değildir. Beklenmeyen bir sunucu hatasında da gövde bu biçimde olmayabilir; böyle bir 5xx yanıtını aynı Idempotency-Key ile yeniden deneyin.

Asistan yanıt vermediğinde mesaj nereye gider

plan_required, assistant_quota_exhausted, ai_turn_ceiling ve assistant_paused asistanın yanıt veremediğini söyler. Mesajın ne olduğu sohbete bağlıdır:

Sohbet zaten açıksa ziyaretçinin mesajı kaydedilir ve ekibe ulaşır. message bunu "Mesajınız ekibe iletildi." diye söyler; assistant_quota_exhausted'te "Mesajınız ekibe iletildi, ekipten biri size yanıt verecek." der. Ekibin yanıtı sohbetin mesajlarında gelir: Asistan yanıt vermediğinde.
Yeni bir sohbet açılacaksa hiçbir şey kaydedilmez ve sohbet açılmaz. message "Biraz sonra yeniden deneyin." der.

assistant_unavailable da iki türlü gelir. Asistan tura hiç başlayamadıysa hiçbir şey olmamıştır ve message "Biraz sonra yeniden deneyin." der. Tur başlayıp yarıda kaldıysa ziyaretçinin mesajı kaydedilmiştir ve message "Mesajınız ekibe iletildi." der; aynı anahtarla yeniden gönderirseniz mesaj ikinci kez kaydedilmez, asistan onu yanıtlar.

`type` değerleri

`type`	Hangi hatalarda
`invalid_request_error`	`400`, `404`, `409`, `413` ve `422`
`authentication_error`	`401`
`permission_error`	`403`
`insufficient_quota`	`402` `plan_required` ve `429` `assistant_quota_exhausted`
`rate_limit_error`	`429` `rate_limit_exceeded`, `ai_turn_ceiling`, `file_download_limit` ve `file_egress_limit`
`server_error`	`503`

Yanıt başlıkları

Başlık	Ne işe yarar
`x-request-id`	İsteğin kimliği, her yanıtta gelir. Destek isterken bunu paylaşın.
`retry-after`	Kaç saniye sonra yeniden deneyebileceğiniz.
`x-should-retry`	`false` gelirse aynı isteği yeniden göndermeyin. OpenAI SDK'ları buna kendiliğinden uyar.
`x-sone-conversation-id`	Sohbetin kimliği. Bir tur yanıtında gelir; akışta, akış başlarken.
`x-sone-error-code`	Yalnız `POST /chat` hatalarında: hatanın kodu. Tarayıcıdaki koda açılmaz.

Tarayıcıdaki kodunuz x-request-id, retry-after, x-should-retry ve x-sone-conversation-id başlıklarını okuyabilir.

Yeniden denemek

x-should-retry: false gelirse yeniden denemeyin; aynı istek aynı sonucu alır. Bu başlık plan_required, assistant_quota_exhausted, ai_turn_ceiling, idempotency_key_reused, conversation_model_mismatch ve conversation_full ile, mesaj ekibe ulaştıysa assistant_paused ile de gelir.
Retry-After başlığı varsa ve x-should-retry: false yoksa o kadar bekleyip yeniden deneyin. rate_limit_exceeded, conversation_busy, assistant_paused, assistant_unavailable, file_download_limit ve file_egress_limit bu başlığı taşır. ai_turn_ceiling de taşır ama yeniden denemeyin.
Retry-After taşımayan 503 yanıtlarında ve ağ hatalarında aynı isteği aynı Idempotency-Key başlığıyla yeniden gönderin. Artan aralıklarla bekleyin: önce 1, sonra 2, 4 ve 8 saniye. Sonecentral aynı mesajı ikinci kez kaydetmez. Örnek ve tarayıcı anahtarındaki tek istisna: Tekrar denemek.
conversation_busy bir yarış durumudur: aynı sohbete aynı anda iki mesaj gitti. Arayüzünüzde bir tur bitmeden yenisini göndermeyin.
Geri kalan 4xx hatalarında yeniden denemek işe yaramaz; isteği düzeltin.

OpenAI SDK'ları 408, 409, 429 ve 5xx yanıtlarını varsayılan olarak iki kez kendiliğinden yeniden dener. x-should-retry başlığına uyar; retry-after en fazla 60 saniyeyse o kadar bekler. Idempotency-Key başlığını ise kendileri eklemez; isteğin seçeneklerinde siz verin: Chat Completions.

Akış sırasında hata

"stream": true gönderseniz de anahtar, sınır, asistan, sohbet ve paket kontrolleri akış başlamadan yapılır. Bu kontrollerden geçmeyen istek yukarıdaki gibi sıradan bir HTTP hatası alır. Akış başladıktan sonra bir hata olursa HTTP durumu artık değişemez. Bu durumda akışa bir hata yazılır ve akış kapanır:

Chat Completions: data: {"error": {…}} parçası, yukarıdaki error nesnesiyle; ardından data: [DONE]. OpenAI SDK'ları bunu hata olarak fırlatır.
Responses: önce type, code, message, param ve sequence_number taşıyan bir error olayı, ardından response.failed. response.failed olayındaki yanıtın status değeri failed olur, error alanı aynı code ve message'ı taşır. [DONE] gelmez. OpenAI'nin Node SDK'sı error olayında APIError fırlatır, kod error.code'dadır; Python SDK'sı onu type değeri "error" olan bir olay olarak verir.
Vercel AI SDK: {"type":"error","errorText":"…"} parçası, ardından data: [DONE]. useChat'in status değeri error olur ve error.message bu metni taşır.

Akış başladıktan sonra gelebilecek hatalar ai_turn_ceiling, sınır tur sırasında dolarsa, ve tur yarıda kalırsa assistant_unavailable'dır. Hata gelmeden önce gönderilen mesajlar sohbete kaydedilmiştir. Onları GET /conversations/{id}/messages ile okuyabilirsiniz.

Kullanıcıya ne gösterilir

message alanı ziyaretçiye gösterilebilir ama çoğu zaman daha iyisi, ziyaretçinin yapabileceği bir şeyi söylemektir. Örneğin 429 ve 503 için "Şu an yanıt veremiyoruz, birazdan yeniden deneyin." Açık bir sohbette ai_turn_ceiling, assistant_quota_exhausted, plan_required ya da assistant_paused geldiyse mesaj ekibe ulaşmıştır: "Mesajınız ekibimize ulaştı, en kısa sürede buradan yanıt vereceğiz." Hata kodlarını ziyaretçiye göstermeyin.

KodlarBaşlık bağlantısını kopyala

Asistan yanıt vermediğinde mesaj nereye giderBaşlık bağlantısını kopyala

type değerleriBaşlık bağlantısını kopyala

Yanıt başlıklarıBaşlık bağlantısını kopyala

Yeniden denemekBaşlık bağlantısını kopyala

Akış sırasında hataBaşlık bağlantısını kopyala

Kullanıcıya ne gösterilirBaşlık bağlantısını kopyala