Սխալների մշակում
Ձախողվող հարցումը վերադարձնում է HTTP կարգավիճակի կոդ և JSON մարմին՝ սխալի տեսակով և հաղորդագրությամբ։ Այս էջը թվարկում է յուրաքանչյուր կարգավիճակ, ցույց է տալիս սխալի մարմինը API-ի յուրաքանչյուր ձևաչափում և ասում է, թե որ սխալների դեպքում արժե կրկին ուղարկել։
SDK-ները բարձրացնում են սխալի օբյեկտ, որը կրում է կարգավիճակի կոդը և մարմնի դաշտերը։ Այս հարցումը նշում է գոյություն չունեցող մոդել.
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 կարգավիճակ և այս մարմինը.
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Սխալի մարմին
Կան երկու մարմին։ /v1/messages-ը պատասխանում է Anthropic ձևաչափով. մնացած բոլոր endpoint-ները՝ OpenAI ձևաչափով։ Երկուսում էլ մանրամասները error.type-ում և error.message-ում են, ուստի մեկ ընթերցիչը սպասարկում է բոլոր endpoint-ները։
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Դաշտ | Տեսակ | Նկարագրություն |
|---|---|---|
error.type | string | Սխալի տեսակը։ Տես ստորև «Սխալների տեսակներ»։ |
error.message | string | Նախադասություն մարդու համար։ Ստորև աղյուսակների տեքստերը կայուն են՝ բացառությամբ փոփոխական մասերի, որոնք նշված են որպես <id>, <n> կամ …։ |
error.code | string | null | Առկա է OpenAI ձևաչափի որոշ սխալների վրա՝ invalid_api_key 401-ի դեպքում, request_too_large 413-ի դեպքում, context_length_exceeded՝ երբ զրույցը չափազանց երկար է, այլապես null է կամ բացակայում է։ Նախ որոշեք ըստ կարգավիճակի և error.type-ի, իսկ code-ը համարեք լրացուցիչ։ |
error.param | null | Առկա է code-ի նույն սխալների վրա։ Միշտ null։ |
type | string | Միայն Anthropic ձևաչափում։ Միշտ error։ |
Սխալների տեսակներ
| Տեսակ | Կարգավիճակներ | Նկարագրություն |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Հենց հարցումն է սխալ՝ դաշտը, մարմինը, մոդելի id-ն կամ մուտք, որը մոդելը չի ընդունում։ Կրկին ուղարկելուց առաջ փոխեք հարցումը։ |
authentication_error | 401 | API բանալին բացակայում է, անհայտ է կամ չեղարկված է։ |
not_found_error | 404 | Ուղին գոյություն չունի։ |
rate_limit_error | 429 | Մնացորդը չի ծածկում հարցումը, flood-պաշտպանությունը կանգնեցրել է այն, կամ մոդելը զբաղված է։ Հաղորդագրությունն ասում է, թե որն է։ |
api_error | 500, 502, 503, 504 | Հարցումը ճիշտ էր, և ձախողումը մեր կողմից է։ Ուղարկեք կրկին։ |
server_error | 500 | Հարցումը ճիշտ էր, և ձախողումը մեր կողմից է։ Ուղարկեք կրկին։ |
Կարգավիճակի կոդեր
| Կարգավիճակ | Տեսակ | Հաղորդագրություն | Երբ |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Մարմինը վավեր JSON չէ։ |
400 | invalid_request_error | unknown model: <id> | model-ը հրապարակված id չէ։ /v1/responses-ում նաև այն դեպքում, երբ model-ը բացակայում է։ |
400 | invalid_request_error | No user message provided | Shannon մակարդակներ. հարցումը օգտատիրոջ տեքստ չի պարունակում։ |
400 | invalid_request_error | <id> does not accept image input | Պատկեր է ուղարկվել hosted open-weight մոդելին, որը պատկերի մուտք չունի։ |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Աուդիո կամ վիդեո մաս է ուղարկվել hosted open-weight մոդելին։ |
400 | invalid_request_error | <id> does not accept response_format | Կառուցվածքային արդյունք է պահանջվել hosted open-weight մոդելից, որը դա չունի։ |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | JSON schema է ուղարկվել hosted open-weight մոդելին, որն ընդունում է միայն json_object։ |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Reasoning effort-ը նշված արժեքներից մեկը չէ։ Hosted open-weight մոդելներ։ |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Թոքենների հաշվարկ է պահանջվել hosted open-weight մոդելներից դուրս մոդելի համար։ |
401 | authentication_error | Missing authentication | API բանալի չի ուղարկվել։ |
401 | authentication_error | Invalid API key | Բանալին անհայտ է, փոխարինվել է ավելի նորով կամ չեղարկվել է։ |
404 | not_found_error | Not Found | Ուղին գոյություն չունի, օրինակ՝ /v1/embeddings։ |
405 | api_error | Method Not Allowed | Ուղին գոյություն ունի, բայց ոչ այս HTTP մեթոդով։ |
413 | invalid_request_error | Failed to buffer the request body: … | Հարցման մարմինը մեծ է 32 MiB-ից։ |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Content-Type header-ը բացակայում է կամ application/json չէ։ |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Պարտադիր դաշտը բացակայում է, օրինակ՝ messages, կամ դաշտն ունի սխալ JSON տեսակ։ |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Հարցման ելքի սահմանը մեծ է ձեր մնացորդից։ |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood-պաշտպանություն. ձեր հաշվից մեկ րոպեում ավելի քան 120 հարցում։ <n>-ը րոպեի ավարտին մնացած վայրկյանների քանակն է։ |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 /v1/chat/completions-ում և /v1/messages-ում. ձեր պլանի Shannon Coder կանչերն ընթացիկ 4-ժամյա պատուհանի համար սպառվել են։ |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Մոդելը տվյալ պահին զբաղված է։ |
500 | server_error | The model backend failed to answer. Please retry. | Մոդելը պատասխան չի ստեղծել։ |
500 | server_error | An internal error occurred. Please retry. | Ներքին ձախողում հարցումը պատրաստելիս։ |
502 | api_error | The model backend failed to answer. Please retry. | Մոդելը պատասխան չի ստեղծել։ Shannon 3 ընտանիք և hosted open-weight մոդելներ։ |
503 | api_error | Could not verify your quota right now. Please retry. | Ձեր մնացորդը տվյալ պահին հնարավոր չեղավ կարդալ։ |
503 | api_error | token counting is temporarily unavailable for this model | Թոքենների հաշվարկը այս մոդելի համար տվյալ պահին հասանելի չէ։ |
504 | api_error | upstream timed out | Hosted open-weight մոդելը հոսքով չուղարկվող հարցման ժամանակային սահմանից ավելի երկար է տևել։ |
Ստուգումները կատարվում են այս հերթականությամբ՝ API բանալի, հարցման մարմին, մոդելի id, flood-պաշտպանություն, մնացորդ։ Սխալ բանալիով և սխալ մարմնով հարցումը հետևաբար վերադարձնում է 401։ 4xx կարգավիճակով մերժված հարցումը չի գանձվում։
Մնացորդ և flood-պաշտպանություն
Յուրաքանչյուր հարցում սպասարկվում է հավասարապես. արագության մակարդակներ և առանձին API քվոտա չկան։ Այնուամենայնիվ երկու բան կարող է պատասխանել 429-ով, երկուսն էլ rate_limit_error տեսակով։ Հաղորդագրությունը տարբերակում է դրանք։
Մնացորդ
Ձեր մնացորդը այսօրվա պլանի քվոտան է, որը նորացվում է 00:00 UTC-ին, և դրանից հետո՝ գնված կրեդիտը։ Չատը և API-ն օգտագործում են նույն մնացորդը։
Յուրաքանչյուր հարցում նախ առանձնացնում է իր ելքի սահմանը՝ max_tokens, կամ max_output_tokens /v1/responses-ում, 4,096, երբ ոչ մեկը չեք ուղարկել։ Երբ պատասխանն ավարտվում է, առանձնացված քանակը փոխարինվում է հարցման օգտագործածով։ Եթե քանակը չի տեղավորվում մնացած մնացորդի մեջ, հարցումը մոդելի սկսվելուց առաջ վերադարձնում է Quota exceeded։
Միաժամանակ աշխատող հարցումներից յուրաքանչյուրն առանձնացնում է իր քանակը։ Բարձր max_tokens-ով շատ զուգահեռ հարցումներ կարող են ժամանակավորապես սպառել մնացորդը՝ նույնիսկ եթե յուրաքանչյուր պատասխան կարճ է։ Ավելի ցածր max_tokens-ն ավելի քիչ է առանձնացնում։
Flood-պաշտպանություն
Flood-պաշտպանությունը թույլ է տալիս 120 հարցում րոպեում մեկ հաշվի համար։ Այն հաշվում է հաշվին, ոչ թե բանալուն, /v1/chat/completions-ը, /v1/responses-ը և /v1/messages-ը միասին։ Րոպեն սկսվում է ձեր առաջին հարցումից։
Այդ րոպեի ներսում 121-րդ հարցումը վերադարձնում է Too many requests. Retry in <n>s. և ոչինչ չի արժենում։ Մերժված հարցումները նույնպես հաշվվում են, ուստի սպասելու փոխարեն կրկին ուղարկող կլիենտը մերժված է մնում, մինչև րոպեն ավարտվի։ Սպասեք հաղորդագրության մեջ նշված <n> վայրկյանը։
Զուգահեռ ուղարկված հարցումները զուգահեռ լինելու համար չեն մերժվում։ Նրանք սպասում են հերթում և պատասխանվում են հերթով։
GET /v1/models-ը և թոքենների հաշվարկի endpoint-ները չեն հաշվվում։
Ավելին սահմանաչափերի և մնացորդի մասին, և որտեղ տեսնել ձեր սեփական մնացորդն ու օգտագործումը. Սահմանաչափեր և մնացորդ Բանալիներ և օգտագործում
Ինչը կրկնել
Հարցումը կրկին ուղարկեք միայն այն դեպքում, երբ նույն հարցումը կարող է հաջողվել։ OpenAI և Anthropic SDK-ներն արդեն ինքնուրույն կրկնում են 429 և 5xx պատասխանները երկու անգամ. փոխելու համար սահմանեք max_retries (JavaScript-ում՝ maxRetries)։
| Սխալ | Կրկին ուղարկե՞լ | Ինչպես |
|---|---|---|
400, 404, 405, 413, 415, 422 | Ոչ։ Նախ ուղղեք հարցումը։ | Հաղորդագրությունը նշում է սխալ դաշտը, մոդելը կամ մուտքը։ |
401 | Ոչ։ Օգտագործեք վավեր բանալի։ | Ստեղծեք կամ փոխարինեք բանալին «Բանալիներ և օգտագործում» էջում։ |
429 Too many requests | Այո, սպասելուց հետո։ | Սպասեք հաղորդագրության մեջ նշված վայրկյանների քանակը, ապա ուղարկեք նույն հարցումը։ |
429 Quota exceeded | Այս տեսքով՝ ոչ։ | Նվազեցրեք max_tokens-ը, սպասեք օրական նորացմանը՝ 00:00 UTC-ին, կամ ավելացրեք կրեդիտ։ |
429 Shannon Coder call quota reached | Այո, հաջորդ պատուհանում։ | Պատուհանները սկսվում են ամեն 4 ժամը մեկ՝ 00:00 UTC-ից։ Մեկ այլ մոդել պատասխանում է անմիջապես։ |
429 … temporarily busy | Այո։ | Սպասեք մի քանի վայրկյան, հետո՝ ամեն հաջորդ փորձի ժամանակ ավելի երկար։ |
500, 502, 503 | Այո։ | Սպասեք 1 վայրկյան, ապա 2, 4 և 8։ Մի քանի փորձից հետո կանգ առեք և հայտնեք հարցման id-ն։ |
504 | Այո։ | Ուղարկեք stream-ը true սահմանած. ժամանակային սահմանը կիրառվում է հոսքով չուղարկվող պատասխանների վրա։ |
Կրկնման ցիկլ, որը հետևում է այս աղյուսակին.
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); Սխալներ հոսքի ներսում
Հոսքն իր առաջին բայթից ունի 200 կարգավիճակ։ Դրանից հետո ձախողումը գալիս է որպես իրադարձություն հոսքի ներսում՝ error անդամով chunk /v1/chat/completions-ում, error իրադարձություն /v1/messages-ում, response.failed կամ error իրադարձություն /v1/responses-ում։ Հոսքի փակող իրադարձությունները այնուամենայնիվ հաջորդում են։ Այդպիսի պատասխանը համարեք ձախողված և հարցումը կրկին ուղարկեք, ինչպես 5xx կարգավիճակի դեպքում։
Մոդելի համատեքստի պատուհանից երկար զրույցը այսպես է նշվում՝ invalid_request_error տեսակով և context_length_exceeded կոդով։ Կրկին ուղարկելուց առաջ կրճատեք զրույցը։
Ճշգրիտ շրջանակները նկարագրված են streaming-ի էջում։ Ստրիմինգ
Հարցման id-ներ
Յուրաքանչյուր պատասխան, ներառյալ սխալները, ունի x-request-id header։ Դա այն արժեքն է, որը դուք ուղարկել եք ձեր x-request-id header-ում, կամ 12 տասնվեցական նիշ, եթե ոչինչ չեք ուղարկել։ Գրանցեք այն մատյանում և նշեք, երբ հարցման հետ կապված օգնություն եք խնդրում։