Hata işleme
API hatalarını kullanıcılara ulaşmadan önce ele alın.
Kimlik doğrulama hataları, kullanım kuralları, hız sınırları, doğrulama hataları ve bağımlılık hataları için öngörülebilir kurtarma yolları oluşturun.
Son güncelleme: July 12, 2026. Examples kullanım safe placeholders ve yap değil içerir real API anahtarıs veya customer promptlar.
İstemci tarafı kuralı
Arızanın hatalarını ayıklamak için yeterli bağlamı günlüğe kaydedin, ancak hiçbir zaman ham API anahtarlarını, gizli dizileri, ödeme verilerini veya tam müşteri istemlerini günlüğe kaydetmeyin.
Arıza haritası
Başarısızlık sınıfıyla başlayın.
Entegrasyon sorunlarının çoğu olmakş gruptan birine girer. Önce yanıtı sınıflandırın, ardından bir sonraki eylemi seçiçinde.
Kimlik doğrulama hataları
Yeniden denemeden önce Yetkilendirme başlığını, anahtar biçimini, etkin durumu, son kullanma tarihini, IP izin verilenler listesini ve gerekli uç nokta kapsamını onaylayın.
Kota aşıldı
Kota hataları, isteğin istekler, belirteçler veya resimler için paket sınırını aşacağı anlamına gelir. Kullanımı azaltın, sıfırlamayı bekleyin veya paket kapasitesini değiştirin.
Doğrulama hataları
Geçersiz JSON, eksik alanlar, desteklenmeyen değerler ve hatalı biçimlendirilmiş veriler, aynı istek tekrar gönderilmeden önce istemci tarafında düzeltilmelidir.
Bağımlılık hataları
İsteğiniz kabul edildikten sonra dahili bir bağımlılık veya ağ yolu başarısız olabilir. Geçici 5xx hatalarını sınırlı yeniden denemelerle tedavi edin ve destek bağlamının düzenlenmesini sağlayın.
Destek yükseltme
Yönlendirme etkinleştirildiğinde tekrarlanan hataları uç nokta, zaman damgası, durum, hata kodu, ortam, maskeli anahtar öneki ve herhangi bir istek kimliği veya sağlayıcı izleme kimliğiyle iletin.
Tepki şekli
OpenAI uyumlu hata nesnesini ayrıştırın.
Check HTTP durum ilk, sonra branch üzerinde error.code içiçinde kurtarma path.
{
"error": {
"message": "Missing or invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key"
}
}| Durum | Kodlar | Ortak neden | Sonraki eylem |
|---|---|---|---|
| 400 | geçersiz_json, geçersiz_payload | İstek gövdesi geçerli değil JSON veya uç nokta şemasıyla eşleşmiyor. | Yükü düzeltin ve yalnızca doğrulama geçtikten sonra yeniden gönderin. |
| 401 | geçersiz_api_anahtarı | API anahtarı eksik, hatalı biçimlendirilmiş veya tanınmıyor. | Taşıyıcı belirtecini, ortam değişkenini ve anahtar önekini kontrol edin. |
| 402 | abonelik_etkin değil, abonelik_kullanılamıyor | Anahtara eklenen abonelik API'ye erişemez. | Müşteriye yönelik daha fazla trafik göndermeden önce faturalandırma durumunu inceleyin. |
| 403 | inaktif_api_anahtarı, süresi dolmuş_api_anahtarı, ip_not_allowed, yetersiz_kapsam | Anahtar biliniyor ancak durum, süre sonu, IP politikası veya kapsam nedeniyle engelleniyor. | Anahtarı döndürün veya güncelleyin, ardından gerekli kapsamı yeniden deneyin. |
| 429 | istek_quota_exceeded, token_quota_exceeded, image_quota_exceeded, quota_exceeded | İstek paket kotasını aşacak. | İstek boyutunu azaltın, kota süresini bekleyin veya daha büyük bir paket seçin. |
| 429 | oran_limit_aşıldı | İstemci, istekleri yerel hız sınırının izin verdiğinden daha hızlı gönderiyor. | Mevcut olduğunda Yeniden Deneme Sonrası'na saygı gösterin ve üstel geri alma özelliğini kullanın. |
| 501 | akış_not_enabled | İstenen özellik tanındı ancak uç nokta için etkinleştirilmedi. | Desteklenmeyen seçeneği devre dışı bırakın veya özellik gerekiyorsa destek ekibiyle iletişime geçin. |
| 5xx | Yanıt gövdesini kontrol edin | Bir iç bağımlılık veya ağ yolu başarısız oldu. | Geri çekilme ile bağımsız çalışmayı yeniden deneyin, ardından tekrarlanan hataları bağlamla iletin. |
Kılavuzu yeniden dene
Yalnızca düzelebilecek arızaları yeniden deneyin.
Yeniden denemeler, geçici baskı veya bağımlılık hatalarında yardımcı olur. Hiçbir şey değişmezse doğrulama, izinler ve faturalandırma sorunlarını daha gürültülü hale getirirler.
Geri alma ile yeniden dene
429 oran_limit_aşıldı, 408, 500, 502, 503, 504
Titreşimle sınırlı üstel geri çekilmeyi kullanın. Yanıt bunu içerdiğinde Yeniden Deneme-Sonra'ya saygı gösterin.
Değiştirmeden tekrar denemeyin
400, 401, 402, 403, 501
Aynı aramayı tekrar denemeden önce isteği, anahtarı, fatura durumunu, izni veya özellik işaretini düzeltin.
Kapasite değişikliklerinden sonra yeniden deneyin
429 kota kodu
Kota hataları genellikle anında yeniden denemeler yerine daha küçük yüklere, gecikmeli çalışmaya veya paket değişikliğine ihtiyaç duyar.
async function callWithBackoff(runRequest) {
for (let attempt = 0; attempt < 3; attempt += 1) {
const response = await runRequest();
if (response.ok) {
return response;
}
const retryable = [408, 429, 500, 502, 503, 504].includes(response.status);
if (!retryable) {
return response;
}
const retryAfter = Number(response.headers.get("retry-after") ?? 0);
const delayMs = retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
return runRequest();
}Uygulama notları
Tek bir kullanıcı eyleminin trafikte artış yaratmaması için yeniden deneme girişimlerini sınırlı tutun.
Eş zamanlı trafik gönderen üretim istemcilerine titreşim ekleyin.
Başarısızlığı gizlemek yerine, son yeniden denemeden sonra yararlı bir kullanıcı mesajı gösterin.
Yeniden deneme döngüsünden çıkmadan önce düzeltilmiş tanılamayı yakalayın.
Eskalasyon
Destek ekibine harekete geçebilecekleri bağlamı gönderin.
İyi bir yükseltme paketi, sırları, istemleri veya müşteri verilerini açığa çıkarmadan önceliklendirmeyi kısaltır.
Desteğe başvurunSSS
Soruların işlenmesinde hata oluştu.
Müşterim hangi hata şeklini beklemeli?
/v1 API, error.message, error.type ve error.code içeren OpenAI uyumlu JSON hata nesnesini döndürür. Doğrulama hataları alan düzeyinde ayrıntıları da içerebilir.
Her 429 yanıtını yeniden denemeli miyim?
Hayır. Varsa Retry-After'ı kullanarak kısa oran_limit_aşımı yanıtlarını yeniden deneyin. Kota kodları içiçinde kullanımı azaltın, sıfırlamayı bekleyin veya daha fazla kapasiteli bir paket seçiçinde.
Desteğe ne göndermeliyim?
Uç noktayı, yöntemi, zaman damgasını, durumu, hata kodunu, maskeli anahtar önekini, ortamı ve herhangi bir istek kimliğini paylaşın. Harici izleme kimliklerini yalnızca destek istediğinde ekleyin. Ham API anahtarlarını, sırlarını veya müşteri istemlerini göndermeyin.
Ücretsiz araçlar
Ücretsiz araçlarla hata ayıklama
Hata kodlarını arayın, 429 yanıtın kodunu çözün, yeniden denemeleri simüle edin ve hız sınırı izlemeyi planlayın.
Hata Kodu Arama
unlimitedcodex hata kodlarını, HTTP durumlarını, yeniden deneme kılavuzunu ve kurtarma eylemlerini arayın.
429 Dekoder
Hız sınırı ve kota basıncını sınıflandırmak için 429 yanıt gövdesini ve başlıklarını yapıştırın ve yeniden deneme kılavuzuna bakın.
Simülatörü Yeniden Dene
Simüle edilmiş sonuçları görmek ve yeniden deneme işleyicisi pasajını kopyalamak için geri alma ve yeniden deneme ayarlarını yapın.
Oran Limiti Planlayıcısı
Beklenen RPS ve ekip boyutuna göre geri çekilme ayarlarını ve kota izleme kontrol listesini planlayın.