Xəta idarəetməsi
Uğursuz olan sorğu HTTP status kodu və xəta tipi ilə mesajı olan JSON gövdəsi qaytarır. Bu səhifə hər statusu siyahıya alır, hər API formatının xəta gövdəsini göstərir və hansı xətaları yenidən göndərməyə dəyər olduğunu bildirir.
SDK-lar status kodunu və gövdənin sahələrini daşıyan xəta obyekti qaldırır. Bu sorğu mövcud olmayan modelin adını göstərir:
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"}]
}' O, 400 statusunu və bu gövdəni qaytarır:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Xəta gövdəsi
İki gövdə var. /v1/messages Anthropic formatında cavab verir; hər digər endpoint OpenAI formatında cavab verir. Hər ikisində təfərrüatlar error.type və error.message daxilindədir, buna görə bir oxuyucu bütün endpoint-lərə xidmət edir.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Sahə | Tip | Təsvir |
|---|---|---|
error.type | string | Xətanın növü. Aşağıda Xəta tiplərinə baxın. |
error.message | string | İnsan üçün cümlə. Aşağıdakı cədvəllərdəki mətnlər <id>, <n> və ya … kimi göstərilən dəyişən hissələrinə qədər sabitdir. |
error.code | string | null | OpenAI formatının bəzi xətalarında olur: 401 ilə invalid_api_key, 413 ilə request_too_large, söhbət çox uzun olduqda context_length_exceeded, əks halda null və ya yoxdur. Əvvəlcə statusa və error.type sahəsinə əsasən qərar verin, code sahəsini isə əlavə hesab edin. |
error.param | null | code ilə eyni xətalarda olur. Həmişə null. |
type | string | Yalnız Anthropic formatı. Həmişə error. |
Xəta tipləri
| Tip | Statuslar | Təsvir |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Sorğunun özü yanlışdır: sahə, gövdə, model id-si və ya modelin qəbul etmədiyi giriş. Yenidən göndərməzdən əvvəl sorğunu dəyişin. |
authentication_error | 401 | API açarı yoxdur, tanınmır və ya ləğv edilib. |
not_found_error | 404 | Yol mövcud deyil. |
rate_limit_error | 429 | Balans sorğunu ödəmir, flood protection onu dayandırıb və ya model məşğuldur. Mesaj hansı olduğunu bildirir. |
api_error | 500, 502, 503, 504 | Sorğu düzgün idi, uğursuzluq bizim tərəfdədir. Onu yenidən göndərin. |
server_error | 500 | Sorğu düzgün idi, uğursuzluq bizim tərəfdədir. Onu yenidən göndərin. |
Status kodları
| Status | Tip | Mesaj | Nə vaxt |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Gövdə etibarlı JSON deyil. |
400 | invalid_request_error | unknown model: <id> | model dərc edilmiş id deyil. /v1/responses-da model olmadıqda da bu xəta qaytarılır. |
400 | invalid_request_error | No user message provided | Shannon səviyyələri: sorğuda istifadəçi mətni yoxdur. |
400 | invalid_request_error | <id> does not accept image input | Şəkil girişi olmayan host edilmiş açıq çəkili modelə şəkil göndərilib. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Host edilmiş açıq çəkili modelə audio və ya video hissəsi göndərilib. |
400 | invalid_request_error | <id> does not accept response_format | Strukturlaşdırılmış çıxış onu olmayan host edilmiş açıq çəkili modeldən istənilib. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Yalnız json_object qəbul edən host edilmiş açıq çəkili modelə JSON sxemi göndərilib. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Reasoning effort siyahıdakı dəyərlərdən biri deyil. Host edilmiş açıq çəkili modellər. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Token sayma host edilmiş açıq çəkili modellərdən kənar model üçün istənilib. |
401 | authentication_error | Missing authentication | API açarı göndərilməyib. |
401 | authentication_error | Invalid API key | Açar tanınmır, daha yeni açarla əvəz olunub və ya ləğv edilib. |
404 | not_found_error | Not Found | Yol mövcud deyil, məsələn /v1/embeddings. |
405 | api_error | Method Not Allowed | Yol mövcuddur, lakin bu HTTP metodu ilə yox. |
413 | invalid_request_error | Failed to buffer the request body: … | Sorğu gövdəsi 32 MiB-dan böyükdür. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Content-Type başlığı yoxdur və ya application/json deyil. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | messages kimi tələb olunan sahə yoxdur və ya sahənin JSON tipi yanlışdır. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Sorğunun çıxış limiti balansınızda qalandan böyükdür. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood protection: hesabınızdan bir dəqiqədə 120-dən çox sorğu göndərilib. <n> dəqiqənin bitməsinə qədər saniyələrin sayıdır. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | /v1/chat/completions və /v1/messages üzərində shannon-coder-1: planınızın cari 4 saatlıq pəncərə üçün Shannon Coder çağırışları istifadə olunub. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Model bu anda məşğuldur. |
500 | server_error | The model backend failed to answer. Please retry. | Model cavab yaratmadı. |
500 | server_error | An internal error occurred. Please retry. | Sorğu hazırlanarkən daxili xəta. |
502 | api_error | The model backend failed to answer. Please retry. | Model cavab yaratmadı. Shannon 3 ailəsi və host edilmiş açıq çəkili modellər. |
503 | api_error | Could not verify your quota right now. Please retry. | Balansınız bu anda oxuna bilmədi. |
503 | api_error | token counting is temporarily unavailable for this model | Token sayma bu model üçün bu anda mövcud deyil. |
504 | api_error | upstream timed out | Host edilən açıq çəkili model axın olmayan sorğunun vaxt limitindən uzun çəkdi. |
Yoxlamalar bu ardıcıllıqla aparılır: API açarı, sorğu gövdəsi, model id-si, flood protection, balans. Buna görə yanlış açarı və yanlış gövdəsi olan sorğu 401 qaytarır. 4xx statusu ilə rədd edilən sorğu hesablanmır.
Balans və flood protection
Hər sorğuya bərabər xidmət göstərilir: sürət səviyyələri yoxdur və ayrıca API kvotası yoxdur. Yenə də iki şey 429 ilə cavab verə bilər, hər ikisi rate_limit_error tipi ilə. Onları mesaj bir-birindən ayırır.
Balans
Balansınız bugünkü plan limitindən (00:00 UTC-də sıfırlanır) və ondan sonra alınmış kreditdən ibarətdir. Çat və API eyni balansdan istifadə edir.
Hər sorğu əvvəlcə çıxış limitini ayırır: max_tokens və ya /v1/responses üzərində max_output_tokens, heç birini göndərməsəniz 4,096. Cavab tamamlandıqda ayrılan məbləğ sorğunun istifadə etdiyi ilə əvəz olunur. Məbləğ qalan balansa sığmırsa, sorğu model başlamazdan əvvəl Quota exceeded qaytarır.
Eyni vaxtda işləyən sorğuların hər biri öz məbləğini ayırır. Buna görə yüksək max_tokens ilə çoxlu paralel sorğu, hər cavab qısa olsa belə, balansı bir anlıq tükədə bilər. Daha kiçik max_tokens daha az ayırır.
Flood protection
Flood protection hesab başına dəqiqədə 120 sorğuya icazə verir. O, /v1/chat/completions, /v1/responses və /v1/messages endpoint-lərini birlikdə, açarı yox, hesabı sayır. Dəqiqə ilk sorğunuzla başlayır.
Həmin dəqiqə daxilində 121-ci sorğu Too many requests. Retry in <n>s. qaytarır və heç nəyə başa gəlmir. Rədd edilən sorğular da sayılır, buna görə gözləmədən yenidən göndərən klient dəqiqə bitənə qədər rədd edilməkdə qalır. Mesajdakı <n> saniyə gözləyin.
Paralel göndərilən sorğular paralel olduqları üçün rədd edilmir. Onlar növbədə gözləyir və növbə ilə cavablanır.
GET /v1/models və token sayma endpoint-ləri sayılmır.
Limitlər və balans haqqında daha çox və öz balansınıza və istifadənizə harada baxmaq barədə: Limitlər və balans Keys & usage
Nəyi təkrar etmək
Sorğunu yalnız eyni sorğu uğurlu ola bildikdə yenidən göndərin. OpenAI və Anthropic SDK-ları 429 və 5xx cavablarını artıq özləri iki dəfə təkrar edir; bunu dəyişmək üçün max_retries (JavaScript-də maxRetries) təyin edin.
| Xəta | Yenidən göndərilsin? | Necə |
|---|---|---|
400, 404, 405, 413, 415, 422 | Xeyr. Əvvəlcə sorğunu düzəldin. | Mesaj yanlış olan sahəni, modeli və ya girişi göstərir. |
401 | Xeyr. Etibarlı açar istifadə edin. | Açarı Keys & usage səhifəsində yaradın və ya əvəz edin. |
429 Too many requests | Bəli, gözləmədən sonra. | Mesajdakı saniyə qədər gözləyin, sonra eyni sorğunu göndərin. |
429 Quota exceeded | Olduğu kimi yox. | max_tokens dəyərini azaldın, 00:00 UTC-dəki gündəlik sıfırlanmanı gözləyin və ya kredit əlavə edin. |
429 Shannon Coder call quota reached | Bəli, növbəti pəncərədə. | Pəncərələr 00:00 UTC-dən başlayaraq hər 4 saatdan bir başlayır. Başqa model dərhal cavab verir. |
429 … temporarily busy | Bəli. | Bir neçə saniyə gözləyin, sonra hər növbəti cəhddə daha uzun. |
500, 502, 503 | Bəli. | 1 saniyə, sonra 2, 4 və 8 saniyə gözləyin. Bir neçə cəhddən sonra dayanın və sorğu id-sini bildirin. |
504 | Bəli. | Onu stream dəyəri true olmaqla göndərin: vaxt limiti axınsız cavablara tətbiq olunur. |
Bu cədvələ uyğun təkrar cəhd dövrəsi:
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); Axın daxilindəki xətalar
Axının statusu ilk baytdan 200-dür. Bundan sonrakı uğursuzluq axın daxilində hadisə kimi gəlir: /v1/chat/completions üzərində error üzvü olan chunk, /v1/messages üzərində error hadisəsi, /v1/responses üzərində response.failed və ya error hadisəsi. Axının bağlayıcı hadisələri yenə də ardınca gəlir. Belə cavabı uğursuz sayın və sorğunu 5xx statusunda olduğu kimi yenidən göndərin.
Modelin kontekst pəncərəsindən uzun söhbət belə bildirilir, invalid_request_error tipi və context_length_exceeded kodu ilə. Yenidən göndərməzdən əvvəl söhbəti qısaldın.
Dəqiq frame-lər streaming ilə birgə təsvir olunub. Axın
Sorğu id-ləri
Hər cavabda, xətalar daxil, x-request-id başlığı var. Bu, öz x-request-id başlığınızda göndərdiyiniz dəyərdir, heç nə göndərmədikdə isə 12 onaltılıq simvoldur. Onu jurnalda saxlayın və sorğu ilə bağlı kömək istəyərkən qeyd edin.