ሓጋይ ኣስተዳደር
ዝወድቕ ጠለብ HTTP ኮድ ኩነታት ከምኡውን JSON body ምስ ዓይነት ጌጋን መልእኽትን ይመልስ። እዚ ገጽ ነፍሲ ወከፍ ኩነታት ይዝርዝር፣ ናይ ነፍሲ ወከፍ ቅርጺ API error body የርኢ፣ ከምኡውን እንታይ ጌጋታት ደጊም ምልኣኽ ዘገድሶም ይብል።
እቶም SDKs ኮድ ኩነታትን fields ናይ body ዝሓዘ error 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"}]
}' ኩነታት 400 ከምኡውን እዚ body ይመልስ፦
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} ናይ ጌጋ body
ክልተ bodies ኣለዉ። /v1/messages ብቅርጺ Anthropic ይመልስ፤ ነፍሲ ወከፍ ካልእ endpoint ብቅርጺ OpenAI ይመልስ። ኣብ ክልቲኦም ዝርዝራት ኣብ error.type ከምኡውን error.message ኣለዉ፣ ስለዚ ሓደ reader ንኩሎም 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"
}
} | Field | ዓይነት | መግለጺ |
|---|---|---|
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 | እቲ ጠለብ ባዕሉ ጌጋ እዩ፦ ሓደ field፣ እቲ body፣ ሞዴል id ወይ እቲ ሞዴል ዘይቅበሎ ኣተዋዕዎ። ደጊምካ ቅድሚ ምልኣኽካ ነቲ ጠለብ ቀይሮ። |
authentication_error | 401 | API ቁልፊ ጎዲሉ፣ ዘይፍለጥ ወይ ዝተሰረዘ እዩ። |
not_found_error | 404 | እቲ መንገዲ የለን። |
rate_limit_error | 429 | ሚዛን ነቲ ጠለብ ኣየጽንዕን፣ flood protection ኣቋሪጹዎ፣ ወይ እቲ ሞዴል ተጸሚዱ ኣሎ። እቲ መልእኽቲ እቲ ኣየናይ ከም ዝኾነ ይብል። |
api_error | 500, 502, 503, 504 | እቲ ጠለብ ጽቡቕ ነይሩ ከምኡውን እቲ ውድቀት ኣብ ወገንና እዩ። ደጊምካ ልኣኾ። |
server_error | 500 | እቲ ጠለብ ጽቡቕ ነይሩ ከምኡውን እቲ ውድቀት ኣብ ወገንና እዩ። ደጊምካ ልኣኾ። |
ኮዳት ኩነታት
| ኩነታት | ዓይነት | መልእኽቲ | መዓስ |
|---|---|---|---|
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 ደረጃታት፦ እቲ ጠለብ ናይ user ጽሑፍ የብሉን። |
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 | ዝተዋቀረ ውጽኢት ካብ ዘይብሉ ዝተሃንደሰ open-weight ሞዴል ተሓቲቱ። |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | JSON schema json_object ጥራይ ዝቕበል ዝተሃንደሰ open-weight ሞዴል ተላኢኹ። |
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: … | እቲ 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: … | ግዴታ field ጎዲሉ፣ ንኣብነት messages፣ ወይ ሓደ field ጌጋ 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 protection፦ ኣብ ኣካውንትካ ኣብ ሓንቲ ደቒቕ ልዕሊ 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 ከምኡውን ዝተሃንደሱ 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 ሞዴል ካብ ዶባ ግዜ ናይ ዘይ-streamed ጠለብ ዝነውሐ ወሲዱ። |
ምርመራታት ብዚ ትእዛዝ ይግበሩ፦ API ቁልፊ፣ request body፣ ሞዴል id፣ flood protection፣ ሚዛን። ስለዚ ጌጋ ቁልፊን ጌጋ bodyን ዘለዎ ጠለብ 401 ይመልስ። ብ 4xx ኩነታት ዝተነጽገ ጠለብ ኣይኽፈልን።
ሚዛንን ምክልካል flood protectionን
ነፍሲ ወከፍ ጠለብ ብማዕረ ይቐርብ፦ rate ደረጃታት የለን ከምኡውን ፍሉይ API quota የለን። ክልተ ነገራት ግን 429 ክመልሱ ይኽእሉ፣ ክልቲኦም ብዓይነት rate_limit_error። እቲ መልእኽቲ ይፈላልዮም።
ሚዛን
ሚዛንካ ናይ ሎሚ allowance ናይ ፕላን እዩ፣ ኣብ 00:00 UTC ዳግም ዝጅምር፣ ድሕሪኡ ድማ ዝተገዝአ credit። Chat ከምኡውን API ካብ ተመሳሳሊ ሚዛን ይወስዱ።
ነፍሲ ወከፍ ጠለብ መጀመርታ ወሰን ውጽኢቱ ይዕቅብ፦ max_tokens፣ ወይ max_output_tokens ኣብ /v1/responses፣ ክልቲኦም ምስ ዘይልእኽካ 4,096። ምላሽ ምስ ተወድአ፣ እቲ ዝተዓቆበ መጠን ብዝተጠቐመ ይትክእ። እቲ መጠን ኣብቲ ዝተረፈ ሚዛን ምስ ዘይሰንብድ፣ እቲ ጠለብ ቅድሚ እቲ ሞዴል ምጅማሩ Quota exceeded ይመልስ።
ብሓባር ዝሰርሑ ጠለባት ነፍሲ ወከፎም ናቶም መጠን ይዕቅቡ። ስለዚ ብዙሓት ተመሳሳሊ ጠለባት ምስ ልዑል max_tokens ነፍሲ ወከፍ ምላሽ ሓጺር ምስ ዝኸውን እውን ሚዛን ንግዚኣዊ ክውድኡ ይኽእሉ። ትሑት max_tokens ሒደት ይዕቁብ።
Flood protection
Flood protection ኣብ ሓንቲ ደቒቕ 120 ጠለባት ንነፍሲ ወከፍ ኣካውንት የፍቅድ። ኣካውንት እምበር ቁልፊ ኣይቝጽርን፣ ኣብ /v1/chat/completions፣ /v1/responses ከምኡውን /v1/messages ብሓባር። እቲ ደቒቕ ብቀዳማይ ጠለብካ ይጅምር።
ጠለብ ቁጽሪ 121 ኣብ ውሽጢ እቲ ደቒቕ Too many requests. Retry in <n>s. ይመልስ ከምኡውን ዋጋ የብሉን። እቶም ዝተነጸጉ ጠለባት እውን ይቝጸሩ፣ ስለዚ ብዘይ ምጽባይ ደጊሙ ዝልእኽ ክላይንት ክሳብ እቲ ደቒቕ ዝውዳእ ይተነጽግ። ካብቲ መልእኽቲ <n> ሰከንዳት ተጸበ።
ብሓባር ዝልእኹ ጠለባት ብሓባር ስለዝልእኹ ጥራይ ኣይተነጽጉን። ኣብ ሰልፊ ይጽበዩ ከምኡውን ብተራ ይምለሱ።
GET /v1/models ከምኡውን እቶም token ቆጸራ endpoints ኣይቝጸሩን።
ብዛዕባ ገደባትን ሚዛንን ዝያዳ፣ ከምኡውን ሚዛንካን ኣጠቓቕማኻን ኣበይ ከም እትርእዮ፦ ገደባትን ሚዛንን ቁልፍታትን ኣጠቓቕማን
እንታይ ደጊሙ ይፈተን
ጠለብ ደጊምካ ልኣኽ ተመሳሳሊ ጠለብ ክዕወት ምስ ዝኽእል ጥራይ። እቶም OpenAI ከምኡውን Anthropic SDKs ምላሻት 429 ከምኡውን 5xx ባዕሎም ክልተ ግዜ ደጊሞም ይፍትኑ፤ ንምቕያር max_retries (maxRetries ኣብ JavaScript) ኣዘጋጅ።
| ጌጋ | ደጊሙ ይለኣኽ? | ከመይ |
|---|---|---|
400, 404, 405, 413, 415, 422 | ኣይፋሉን። ቅድም ነቲ ጠለብ ኣስተኻኽል። | እቲ መልእኽቲ እቲ ጌጋ field፣ ሞዴል ወይ ኣተዋዕዎ ይሰምዮ። |
401 | ኣይፋሉን። ቅኑዕ ቁልፊ ተጠቐም። | ቁልፊ ኣብ ገጽ ቁልፍታትን ኣጠቓቕማን ፍጠር ወይ ተክእ። |
429 Too many requests | እወ፣ ድሕሪ ምጽባይ። | ኣብ መልእኽቲ ዘሎ ቁጽሪ ሰከንዳት ተጸበ፣ ደሓር ተመሳሳሊ ጠለብ ልኣኽ። |
429 Quota exceeded | ከምዘሎ ኣይፋሉን። | max_tokens ኣንቅስ፣ ዕለታዊ ዳግም ምጅማር ኣብ 00:00 UTC ተጸበ፣ ወይ credit ወስኽ። |
429 Shannon Coder call quota reached | እወ፣ ኣብ ዝቕጽል መስኮት። | እቶም መስኮታት ካብ 00:00 UTC ኣብ ነፍሲ ወከፍ 4 ሰዓታት ይጅምሩ። ካልእ ሞዴል ብቕጽበት ይመልስ። |
429 … temporarily busy | እወ። | ብዙሓት ሰከንዳት ተጸበ፣ ብነፍሲ ወከፍ ቀጻሊ ፈተነ ድማ ዝያዳ። |
500, 502, 503 | እወ። | 1 ሰከንድ ተጸበ፣ ደሓር 2፣ 4 ከምኡውን 8። ድሕሪ ገለ ፈተናታት ደው በል እሞ id ናይ ጠለብ ሕበር። |
504 | እወ። | ምስ stream ናብ true ዝተዘጋጀ ልኣኾ፦ ዶባ ግዜ ኣብ ዘይ-streamed ምላሻት ይትግበር። |
ነዚ ሰንጠረዥ ዝስዕብ 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 ካብ ቀዳማይ byte ኩነታት 200 ኣለዎ። ድሕሪኡ ዝኸውን ውድቀት ከም event ኣብ ውሽጢ stream ይመጽእ፦ chunk ምስ error member ኣብ /v1/chat/completions፣ error event ኣብ /v1/messages፣ response.failed ወይ error event ኣብ /v1/responses። እቶም መዛዘሚ events ናይ stream ግን ይቕጽሉ። ከምዚ ዝበለ ምላሽ ከም ዝወደቐ ርአዮ ከምኡውን እቲ ጠለብ ደጊምካ ልኣኽ፣ ከም ንኩነታት 5xx።
ካብ context window ናይ ሞዴል ዝነውሐ ዘተ በዚ ኣገባብ ይሕበር፣ ምስ ዓይነት invalid_request_error ከምኡውን code context_length_exceeded። ደጊምካ ቅድሚ ምልኣኽካ ዘተ ኣሓጽር።
እቶም ልክዕ frames ምስ streaming ተገሊጾም ኣለዉ። ስትሪም
Ids ናይ ጠለብ
ነፍሲ ወከፍ ምላሽ፣ ጌጋታት ጨሚሩ፣ x-request-id header ኣለዎ። እቲ ኣብ ናትካ x-request-id header ዝለኣኽካዮ ዋጋ እዩ፣ ወይ ዋላ ሓደ ምስ ዘይለኣኽካ 12 hexadecimal ፊደላት። መዝግቦ፣ ብዛዕባ ጠለብ ሓገዝ ክትሓትት ከሎ ድማ ጠቐስዎ።