ስህተት አስተዳደር
የሚከሽፍ ጥያቄ HTTP status ኮድ እና የስህተት ዓይነትና መልእክት ያለው JSON body ይመልሳል። ይህ ገጽ እያንዳንዱን status ይዘረዝራል፣ የእያንዳንዱን API ፎርማት የስህተት body ያሳያል፣ እና እንደገና መላክ የሚገባቸውን ስህተቶች ይነግራል።
SDKs የstatus ኮዱንና የbody መስኮችን የያዘ የስህተት object ያነሳሉ። ይህ ጥያቄ የሌለ ሞዴል ይጠቅሳል፦
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"}]
}' status 400 እና ይህን body ይመልሳል፦
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} የስህተት አካል
ሁለት አይነት body አሉ። /v1/messages በAnthropic ፎርማት ይመልሳል፤ ሌሎች endpoints ሁሉ በOpenAI ፎርማት ይመልሳሉ። በሁለቱም ዝርዝሩ በerror.type እና በerror.message ውስጥ ነው፣ ስለዚህ አንድ አንባቢ ለሁሉም endpoints ይበቃል።
{
"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 ፎርማት ስህተቶች ላይ ይገኛል፦ 401 ሲሆን invalid_api_key፣ 413 ሲሆን request_too_large፣ ውይይቱ በጣም ረጅም ሲሆን context_length_exceeded፣ ካልሆነ null ወይም የለም። መጀመሪያ በstatus እና በerror.type ይወስኑ፣ codeን ደግሞ እንደ ተጨማሪ ይያዙት። |
error.param | null | እንደ code በተመሳሳይ ስህተቶች ላይ ይገኛል። ሁልጊዜ null። |
type | string | በAnthropic ፎርማት ብቻ። ሁልጊዜ error። |
የስህተት ዓይነቶች
| ዓይነት | Statuses | መግለጫ |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | ጥያቄው ራሱ ስህተት ነው፦ መስክ፣ body፣ የሞዴል id ወይም ሞዴሉ የማይቀበለው ግብዓት። እንደገና ከመላክዎ በፊት ጥያቄውን ይቀይሩ። |
authentication_error | 401 | የAPI ቁልፉ የለም፣ አይታወቅም ወይም ተሰርዟል። |
not_found_error | 404 | መንገዱ የለም። |
rate_limit_error | 429 | ቀሪ ሂሳቡ ጥያቄውን አይሸፍንም፣ የጥያቄ ብዛት ጥበቃ አስቆመው፣ ወይም ሞዴሉ ተጠምዷል። መልእክቱ የትኛው እንደሆነ ይናገራል። |
api_error | 500, 502, 503, 504 | ጥያቄው ደህና ነበር፣ ብልሽቱ የእኛ ወገን ነው። እንደገና ይላኩት። |
server_error | 500 | ጥያቄው ደህና ነበር፣ ብልሽቱ የእኛ ወገን ነው። እንደገና ይላኩት። |
የStatus ኮዶች
| ሁኔታ | ዓይነት | መልእክት | መቼ |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | body ትክክለኛ 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 | ምስል የማይቀበል የተስተናገደ open-weight ሞዴል ላይ ምስል ተልኳል። |
400 | invalid_request_error | audio and video input are not supported by any hosted model | የድምፅ ወይም የቪዲዮ ክፍል ወደ የተስተናገደ open-weight ሞዴል ተልኳል። |
400 | invalid_request_error | <id> does not accept response_format | structured output የማይደግፍ የተስተናገደ open-weight ሞዴል ላይ ተጠይቋል። |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | json_object ብቻ ወደሚቀበል የተስተናገደ open-weight ሞዴል JSON schema ተልኳል። |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | የreasoning effort ከተዘረዘሩት እሴቶች አንዱ አይደለም። የተስተናገዱ open-weight ሞዴሎች። |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | የtoken ቆጠራ ከተስተናገዱት 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 method አይደለም። |
413 | invalid_request_error | Failed to buffer the request body: … | የጥያቄው 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. | የጥያቄ ብዛት ጥበቃ፦ በመለያዎ ላይ በአንድ ደቂቃ ከ120 በላይ ጥያቄዎች። <n> ደቂቃው እስኪያልቅ ያሉት ሰከንዶች ብዛት ነው። |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | በ/v1/chat/completions እና በ/v1/messages ላይ shannon-coder-1፦ ለአሁኑ የ4-ሰዓት መስኮት የዕቅድዎ Shannon Coder ጥሪዎች አልቀዋል። |
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 ቤተሰብ እና የተስተናገዱ 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 | የtoken ቆጠራ ለዚህ ሞዴል በዚህ ጊዜ አይገኝም። |
504 | api_error | upstream timed out | የተስተናገደ open-weight ሞዴል stream ላልሆነ ጥያቄ ከተወሰነው የጊዜ ገደብ በላይ ወሰደ። |
ምርመራዎች በዚህ ቅደም ተከተል ይካሄዳሉ፦ API ቁልፍ፣ የጥያቄ body፣ የሞዴል id፣ የጥያቄ ብዛት ጥበቃ፣ ቀሪ ሂሳብ። ስለዚህ የተሳሳተ ቁልፍና የተሳሳተ body ያለው ጥያቄ 401 ይመልሳል። በ4xx status የሚከለከል ጥያቄ አያስከፍልም።
ቀሪ ሂሳብ እና የጥያቄ ብዛት ጥበቃ
እያንዳንዱ ጥያቄ እኩል ይስተናገዳል፦ የፍጥነት ደረጃዎች የሉም፣ የተለየ የAPI quota የለም። ሁለት ነገሮች አሁንም 429 ሊመልሱ ይችላሉ፣ ሁለቱም በrate_limit_error አይነት። መልእክቱ ይለያቸዋል።
ቀሪ ሂሳብ
ቀሪ ሂሳብዎ የዛሬው የዕቅድ ዕለታዊ መጠን ነው፣ እሱም በ00:00 UTC ይታደሳል፣ ከዚያ በኋላ የገዙት ክሬዲት። Chat እና API ከአንድ ቀሪ ሂሳብ ይወስዳሉ።
እያንዳንዱ ጥያቄ መጀመሪያ የውጤት ገደቡን ይመድባል፦ max_tokens፣ ወይም በ/v1/responses ላይ max_output_tokens፣ ሁለቱንም ካልላኩ 4,096። መልሱ ሲጠናቀቅ የተመደበው መጠን ጥያቄው በተጠቀመው ይተካል። መጠኑ በቀረው ቀሪ ሂሳብ ውስጥ ካልገባ ጥያቄው ሞዴሉ ከመጀመሩ በፊት Quota exceeded ይመልሳል።
በአንድ ጊዜ የሚሄዱ ጥያቄዎች እያንዳንዳቸው የራሳቸውን መጠን ይመድባሉ። ስለዚህ ከፍተኛ max_tokens ያላቸው ብዙ ትይዩ ጥያቄዎች እያንዳንዱ መልስ አጭር ቢሆንም ለአጭር ጊዜ ቀሪ ሂሳቡን ሊያሟጥጡ ይችላሉ። ዝቅተኛ max_tokens ያነሰ ይመድባል።
የጥያቄ ብዛት ጥበቃ
የጥያቄ ብዛት ጥበቃ በአንድ መለያ በደቂቃ 120 ጥያቄዎችን ይፈቅዳል። የሚቆጥረው መለያውን እንጂ ቁልፉን አይደለም፣ እና /v1/chat/completions፣ /v1/responses እና /v1/messagesን አንድ ላይ ይቆጥራል። ደቂቃው በመጀመሪያ ጥያቄዎ ይጀምራል።
በዚያ ደቂቃ ውስጥ 121ኛው ጥያቄ Too many requests. Retry in <n>s. ይመልሳል እና ምንም አያስከፍልም። የተከለከሉ ጥያቄዎችም ይቆጠራሉ፣ ስለዚህ ሳይጠብቅ እንደገና የሚልክ client ደቂቃው እስኪያልቅ ድረስ ይከለከላል። በመልእክቱ ውስጥ ያሉትን <n> ሰከንዶች ይጠብቁ።
በትይዩ የተላኩ ጥያቄዎች በትይዩነታቸው ምክንያት አይከለከሉም። ተራ ይጠብቃሉ እና በየተራ ይመለሳሉ።
GET /v1/models እና የtoken መቁጠሪያ endpoints አይቆጠሩም።
ስለ ገደቦችና ቀሪ ሂሳብ ተጨማሪ፣ እንዲሁም የራስዎን ቀሪ ሂሳብና አጠቃቀም የት ማየት እንደሚችሉ፦ ገደቦች እና ቀሪ ሂሳብ Keys & usage
ምን እንደገና መላክ
ጥያቄን እንደገና ይላኩ ተመሳሳዩ ጥያቄ ሊሳካ በሚችልበት ጊዜ ብቻ። የOpenAI እና የAnthropic SDKs የ429 እና የ5xx ምላሾችን ራሳቸው ሁለት ጊዜ እንደገና ይሞክራሉ፤ ይህን ለመቀየር max_retries (በJavaScript maxRetries) ያዋቅሩ።
| ስህተት | እንደገና ይላክ? | እንዴት |
|---|---|---|
400, 404, 405, 413, 415, 422 | አይ። መጀመሪያ ጥያቄውን ያርሙ። | መልእክቱ የተሳሳተውን መስክ፣ ሞዴል ወይም ግብዓት ይጠቅሳል። |
401 | አይ። ትክክለኛ ቁልፍ ይጠቀሙ። | ቁልፉን በKeys & usage ገጽ ላይ ይፍጠሩ ወይም ይተኩ። |
429 Too many requests | አዎ፣ ከጥበቃው በኋላ። | በመልእክቱ ውስጥ ያለውን የሰከንዶች ብዛት ይጠብቁ፣ ከዚያ ተመሳሳዩን ጥያቄ ይላኩ። |
429 Quota exceeded | እንዳለ አይደለም። | max_tokensን ይቀንሱ፣ በ00:00 UTC የሚደረገውን ዕለታዊ ዳግም ማስጀመር ይጠብቁ፣ ወይም ክሬዲት ይጨምሩ። |
429 Shannon Coder call quota reached | አዎ፣ በሚቀጥለው መስኮት። | መስኮቶቹ ከ00:00 UTC ጀምሮ በየ4 ሰዓቱ ይጀምራሉ። ሌላ ሞዴል ወዲያውኑ ይመልሳል። |
429 … temporarily busy | አዎ። | ጥቂት ሰከንዶች ይጠብቁ፣ ከዚያ በእያንዳንዱ ቀጣይ ሙከራ ረዘም ያለ። |
500, 502, 503 | አዎ። | 1 ሰከንድ ይጠብቁ፣ ከዚያ 2፣ 4 እና 8። ከጥቂት ሙከራዎች በኋላ ያቁሙ እና የጥያቄውን id ያሳውቁ። |
504 | አዎ። | streamን ወደ true አዘጋጅተው ይላኩት፦ የጊዜ ገደቡ የሚተገበረው stream ላልሆኑ ምላሾች ነው። |
ይህን ሠንጠረዥ የሚከተል retry loop፦
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); በstream ውስጥ ያሉ ስህተቶች
stream ከመጀመሪያው ባይቱ ጀምሮ status 200 አለው። ከዚያ በኋላ የሚከሰት ብልሽት በstream ውስጥ እንደ event ይመጣል፦ በ/v1/chat/completions ላይ error አባል ያለው chunk፣ በ/v1/messages ላይ error event፣ በ/v1/responses ላይ response.failed ወይም error event። የstream መዝጊያ events አሁንም ይከተላሉ። እንዲህ ያለውን ምላሽ እንደ ያልተሳካ ይውሰዱት እና እንደ 5xx status ጥያቄውን እንደገና ይላኩ።
ከሞዴሉ context window የሚረዝም ውይይት በዚህ መንገድ ይገለጻል፣ በinvalid_request_error አይነት እና በcontext_length_exceeded ኮድ። እንደገና ከመላክዎ በፊት ውይይቱን ያሳጥሩ።
ትክክለኛዎቹ frames ከstreaming ጋር ተብራርተዋል። ስትሪሚንግ
የጥያቄ id ዎች
እያንዳንዱ ምላሽ፣ ስህተቶችንም ጨምሮ፣ x-request-id header አለው። እሱ በራስዎ x-request-id header የላኩት ዋጋ ነው፣ ምንም ካልላኩ ደግሞ 12 የሄክሳዴሲማል ቁምፊዎች። ይመዝግቡት፣ እና ስለ ጥያቄ እርዳታ ሲጠይቁ ይጥቀሱት።