Hata yönetimi
Başarısız olan bir istek, bir HTTP durum kodu ve bir hata türü ile mesaj içeren bir JSON gövdesi döndürür. Bu sayfa her durumu listeler, her API biçiminin hata gövdesini gösterir ve hangi hataların yeniden göndermeye değdiğini söyler.
SDK'lar, durum kodunu ve gövdenin alanlarını taşıyan bir hata nesnesi üretir. Bu istek, var olmayan bir modelin adını verir:
import openai
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com/v1",
)
try:
client.chat.completions.create(
model="no-such-model",
messages=[{"role": "user", "content": "Hello"}],
)
except openai.APIStatusError as error:
print(error.status_code) # 400
print(error.type) # invalid_request_error
print(error.body["message"]) # unknown model: no-such-model
print(error.response.headers.get("x-request-id")) # the id of this request import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
try {
await client.chat.completions.create({
model: "no-such-model",
messages: [{ role: "user", content: "Hello" }],
});
} catch (error) {
if (!(error instanceof OpenAI.APIError)) throw error;
console.log(error.status); // 400
console.log(error.type); // invalid_request_error
console.log(error.error.message); // unknown model: no-such-model
} curl -i https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "no-such-model",
"messages": [{"role": "user", "content": "Hello"}]
}' 400 durumunu ve şu gövdeyi döndürür:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Hata gövdesi
İki gövde vardır. /v1/messages Anthropic biçiminde yanıt verir; diğer her uç nokta OpenAI biçiminde yanıt verir. İkisinde de ayrıntılar error.type ve error.message içindedir; bu yüzden tek bir okuyucu tüm uç noktalara hizmet eder.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Alan | Tür | Açıklama |
|---|---|---|
error.type | string | Hatanın türü. Aşağıdaki Hata türleri bölümüne bakın. |
error.message | string | Bir insan için bir cümle. Aşağıdaki tablolardaki metinler, <id>, <n> veya … olarak gösterilen değişken kısımları dışında kararlıdır. |
error.code | string | null | OpenAI biçimindeki bazı hatalarda bulunur: 401 ile invalid_api_key, 413 ile request_too_large, bir konuşma çok uzun olduğunda context_length_exceeded; diğer durumlarda null veya yok. Önce durum koduna ve error.type değerine göre karar verin ve code alanını ek bilgi sayın. |
error.param | null | code ile aynı hatalarda bulunur. Her zaman null. |
type | string | Yalnızca Anthropic biçiminde. Her zaman error. |
Hata türleri
| Tür | Durumlar | Açıklama |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | İsteğin kendisi yanlış: bir alan, gövde, model kimliği veya modelin kabul etmediği bir girdi. Tekrar göndermeden önce isteği değiştirin. |
authentication_error | 401 | API anahtarı eksik, bilinmiyor veya iptal edilmiş. |
not_found_error | 404 | Yol mevcut değil. |
rate_limit_error | 429 | Bakiye isteği karşılamıyor, flood koruması durdurdu veya model meşgul. Mesaj hangisi olduğunu söyler. |
api_error | 500, 502, 503, 504 | İstek düzgündü ve hata bizim tarafımızda. Tekrar gönderin. |
server_error | 500 | İstek düzgündü ve hata bizim tarafımızda. Tekrar gönderin. |
Durum kodları
| Durum | Tür | Mesaj | Ne zaman |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Gövde geçerli bir JSON değil. |
400 | invalid_request_error | unknown model: <id> | model yayımlanmış bir kimlik değil. /v1/responses üzerinde model eksik olduğunda da. |
400 | invalid_request_error | No user message provided | Shannon katmanları: istekte kullanıcı metni yok. |
400 | invalid_request_error | <id> does not accept image input | Görsel girdisi olmayan host edilen bir açık ağırlıklı modele görsel gönderildi. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Host edilen bir açık ağırlıklı modele ses veya video parçası gönderildi. |
400 | invalid_request_error | <id> does not accept response_format | Yapılandırılmış çıktısı olmayan, host edilen bir açık ağırlıklı modelden yapılandırılmış çıktı istendi. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Yalnızca json_object kabul eden, host edilen bir açık ağırlıklı modele JSON şeması gönderildi. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Akıl yürütme çabası listelenen değerlerden biri değil. Host edilen açık ağırlıklı modeller. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Host edilen açık ağırlıklı modeller dışındaki bir model için token sayımı istendi. |
401 | authentication_error | Missing authentication | API anahtarı gönderilmedi. |
401 | authentication_error | Invalid API key | Anahtar bilinmiyor, daha yenisiyle değiştirilmiş veya iptal edilmiş. |
404 | not_found_error | Not Found | Yol mevcut değil, örneğin /v1/embeddings. |
405 | api_error | Method Not Allowed | Yol mevcut ama bu HTTP yöntemiyle değil. |
413 | invalid_request_error | Failed to buffer the request body: … | İstek gövdesi 32 MiB'dan büyük. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Content-Type başlığı eksik veya application/json değil. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages gibi zorunlu bir alan eksik veya bir alanın JSON türü yanlış. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | İsteğin çıktı sınırı, bakiyenizde kalandan büyük. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood koruması: hesabınızda bir dakikada 120'den fazla istek. <n>, dakikanın bitmesine kalan saniye sayısıdır. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | /v1/chat/completions ve /v1/messages üzerinde shannon-coder-1: planınızın geçerli 4 saatlik penceredeki Shannon Coder çağrıları tükendi. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Model şu anda meşgul. |
500 | server_error | The model backend failed to answer. Please retry. | Model yanıt üretmedi. |
500 | server_error | An internal error occurred. Please retry. | İstek hazırlanırken bir iç hata oluştu. |
502 | api_error | The model backend failed to answer. Please retry. | Model yanıt üretmedi. Shannon 3 ailesi ve host edilen açık ağırlıklı modeller. |
503 | api_error | Could not verify your quota right now. Please retry. | Bakiyeniz şu anda okunamadı. |
503 | api_error | token counting is temporarily unavailable for this model | Token sayma şu anda bu model için kullanılamıyor. |
504 | api_error | upstream timed out | Host edilen bir açık ağırlıklı model, akışsız bir isteğin zaman sınırından daha uzun sürdü. |
Kontroller şu sırayla çalışır: API anahtarı, istek gövdesi, model kimliği, flood koruması, bakiye. Bu yüzden yanlış anahtarlı ve yanlış gövdeli bir istek 401 döndürür. Bir 4xx durumuyla reddedilen istek ücretlendirilmez.
Bakiye ve flood koruması
Her istek eşit şekilde sunulur: hız katmanları ve ayrı bir API kotası yoktur. Yine de iki şey 429 yanıtı verebilir; ikisi de rate_limit_error türündedir. Mesaj bunları birbirinden ayırır.
Bakiye
Bakiyeniz, 00:00 UTC'de sıfırlanan bugünün plan limiti ve ondan sonra satın alınan kredinizdir. Sohbet ve API aynı bakiyeden harcar.
Her istek önce çıktı sınırını ayırır: max_tokens veya /v1/responses üzerinde max_output_tokens; ikisini de göndermezseniz 4,096. Yanıt tamamlandığında ayrılan miktar, isteğin kullandığıyla değiştirilir. Miktar kalan bakiyeye sığmazsa istek, model başlamadan Quota exceeded döndürür.
Aynı anda çalışan istekler kendi miktarlarını ayrı ayrı ayırır. Bu yüzden yüksek max_tokens değerli çok sayıda paralel istek, her yanıt kısa olsa bile bakiyeyi bir an için tüketebilir. Daha düşük bir max_tokens daha az ayırır.
Flood koruması
Flood koruması hesap başına dakikada 120 isteğe izin verir. /v1/chat/completions, /v1/responses ve /v1/messages üzerindeki istekleri birlikte, anahtarı değil hesabı sayar. Dakika ilk isteğinizle başlar.
O dakika içindeki 121. istek Too many requests. Retry in <n>s. döndürür ve hiçbir şeye mal olmaz. Reddedilen istekler de sayılır; bu yüzden beklemeden tekrar gönderen bir istemci, dakika bitene kadar reddedilmeye devam eder. Mesajdaki <n> saniyeyi bekleyin.
Paralel gönderilen istekler paralel oldukları için reddedilmez. Sırada beklerler ve sırayla yanıtlanırlar.
GET /v1/models ve token sayma uç noktaları sayılmaz.
Limitler ve bakiye hakkında daha fazlası ve kendi bakiyenizi ve kullanımınızı nerede göreceğiniz: Limitler ve bakiye Keys & usage
Neler yeniden denenir
Bir isteği yalnızca aynı istek başarılı olabilecekse tekrar gönderin. OpenAI ve Anthropic SDK'ları 429 ve 5xx yanıtlarını zaten kendiliğinden iki kez yeniden dener; bunu değiştirmek için max_retries (JavaScript'te maxRetries) ayarlayın.
| Hata | Tekrar gönderilsin mi? | Nasıl |
|---|---|---|
400, 404, 405, 413, 415, 422 | Hayır. Önce isteği düzeltin. | Mesaj, yanlış olan alanı, modeli veya girdiyi belirtir. |
401 | Hayır. Geçerli bir anahtar kullanın. | Anahtarı Keys & usage sayfasında oluşturun veya değiştirin. |
429 Too many requests | Evet, beklemeden sonra. | Mesajdaki saniye kadar bekleyin, sonra aynı isteği gönderin. |
429 Quota exceeded | Olduğu gibi değil. | max_tokens değerini düşürün, 00:00 UTC'deki günlük sıfırlamayı bekleyin veya kredi ekleyin. |
429 Shannon Coder call quota reached | Evet, sonraki pencerede. | Pencereler 00:00 UTC'den itibaren her 4 saatte başlar. Başka bir model hemen yanıt verir. |
429 … temporarily busy | Evet. | Birkaç saniye bekleyin, sonraki her denemede daha uzun bekleyin. |
500, 502, 503 | Evet. | 1 saniye, sonra 2, 4 ve 8 saniye bekleyin. Birkaç denemeden sonra durun ve istek kimliğini bildirin. |
504 | Evet. | stream değeri true olarak gönderin: zaman sınırı akışsız yanıtlar için geçerlidir. |
Bu tabloyu izleyen bir yeniden deneme döngüsü:
import re
import time
import openai
from openai import OpenAI
# max_retries=0: this loop does the retrying, the SDK does not add its own.
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1", max_retries=0)
def create_with_retry(attempts=5, **request):
for attempt in range(attempts):
try:
return client.chat.completions.create(**request)
except openai.RateLimitError as error:
text = str(error)
flood = re.search(r"Retry in (\d+)s", text)
if flood:
time.sleep(int(flood.group(1))) # flood protection: wait out the minute
elif "temporarily busy" in text:
time.sleep(2 ** attempt)
else:
raise # balance: a wait of seconds does not help
except (openai.InternalServerError, openai.APIConnectionError):
time.sleep(2 ** attempt) # 1, 2, 4, 8 seconds
raise RuntimeError("the request failed after all attempts")
response = create_with_retry(
model="shannon-3",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content) import OpenAI from "openai";
// maxRetries: 0 — this loop does the retrying, the SDK does not add its own.
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1", maxRetries: 0 });
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
async function createWithRetry(request, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
try {
return await client.chat.completions.create(request);
} catch (error) {
const text = String(error.message);
const flood = text.match(/Retry in (\d+)s/);
if (error.status === 429 && flood) {
await sleep(Number(flood[1])); // flood protection: wait out the minute
} else if (error.status === 429 && text.includes("temporarily busy")) {
await sleep(2 ** attempt);
} else if (error.status >= 500 || error instanceof OpenAI.APIConnectionError) {
await sleep(2 ** attempt); // 1, 2, 4, 8 seconds
} else {
throw error; // wrong request, wrong key or balance
}
}
}
throw new Error("the request failed after all attempts");
}
const response = await createWithRetry({
model: "shannon-3",
messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content); Bir akışın içindeki hatalar
Bir akışın durumu ilk baytından itibaren 200'dür. Bundan sonraki bir hata akışın içinde bir olay olarak gelir: /v1/chat/completions üzerinde error üyesi olan bir parça, /v1/messages üzerinde bir error olayı, /v1/responses üzerinde bir response.failed veya error olayı. Akışın kapanış olayları yine de gelir. Böyle bir yanıtı başarısız sayın ve isteği, bir 5xx durumunda olduğu gibi tekrar gönderin.
Modelin bağlam penceresinden uzun bir konuşma bu şekilde, invalid_request_error türü ve context_length_exceeded koduyla bildirilir. Tekrar göndermeden önce konuşmayı kısaltın.
Kesin çerçeveler streaming bölümünde açıklanır. Akış
İstek kimlikleri
Her yanıtta, hatalar dahil, bir x-request-id başlığı vardır. Bu, kendi x-request-id başlığınızda gönderdiğiniz değerdir veya hiçbir şey göndermediyseniz 12 onaltılık karakterdir. Kaydedin ve bir istek hakkında yardım isterken belirtin.