Khaladaadka Maareynta
Codsi fashilmaa wuxuu soo celiyaa koodh xaalad HTTP iyo jidh JSON ah oo leh nooc khalad iyo fariin. Boggani wuxuu liis garaynayaa xaalad kasta, wuxuu muujinayaa jidhka khaladka ee qaab API kasta, wuxuuna sheegayaa khaladaadka mar kale loo dirayo.
SDK-yadu waxay kor u qaadaan shay khalad ah oo sida koodhka xaaladda iyo field-yada jidhka. Codsigani wuxuu magacaabayaa model aan jirin:
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"}]
}' Wuxuu soo celiyaa xaalad 400 iyo jidhkan:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Jidhka khaladka
Laba jidh ayaa jira. /v1/messages wuxuu ku jawaabaa qaabka Anthropic; endpoint kasta oo kale wuxuu ku jawaabaa qaabka OpenAI. Labadaba, faahfaahintu waxay ku jirtaa error.type iyo error.message, sidaas darteed hal akhriye ayaa u adeega endpoint kasta.
{
"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 | Nooc | Sharaxaad |
|---|---|---|
error.type | string | Nooca khaladka. Eeg Noocyada khaladka hoose. |
error.message | string | Weedh qof loogu talagalay. Qoraallada shaxdaha hoose way go'an yihiin marka laga reebo qaybahooda isbeddelaya, oo lagu muujiyay <id>, <n> ama …. |
error.code | string | null | Waxaa ka muuqda khaladaad qaarkood oo qaabka OpenAI ah: invalid_api_key oo leh 401, request_too_large oo leh 413, context_length_exceeded marka wada-hadal aad u dheer yahay, haddii kale null ama maqan. Marka hore ku go'aanso xaaladda iyo error.type, code-na u aqoon sida dheeraad. |
error.param | null | Waxaa ka muuqda isla khaladaadka code. Had iyo jeer null. |
type | string | Qaabka Anthropic oo keliya. Had iyo jeer error. |
Noocyada khaladka
| Nooc | Xaaladaha | Sharaxaad |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Codsigu laftigiisu waa qalad: field, jidhka, id-ga model-ka ama input model-ku aanu qaadan. Beddel codsiga ka hor inta aadan mar kale dirin. |
authentication_error | 401 | Furaha API waa maqan yahay, lama aqoon ama waa la meel mariyay. |
not_found_error | 404 | Jidku ma jiro. |
rate_limit_error | 429 | Haraagga ma daboolo codsiga, flood protection ayaa joojiyay, ama model-ku waa mashquul. Fariintu waxay sheegaysaa kee. |
api_error | 500, 502, 503, 504 | Codsigu wuu fiicnaa fashilkuna wuxuu ku yaal dhinaceenna. Mar kale dir. |
server_error | 500 | Codsigu wuu fiicnaa fashilkuna wuxuu ku yaal dhinaceenna. Mar kale dir. |
Koodhka xaaladda
| Xaalad | Nooc | Fariin | Goorta |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Jidhku ma aha JSON sax ah. |
400 | invalid_request_error | unknown model: <id> | model ma aha id la daabacay. /v1/responses sidoo kale marka model maqan yahay. |
400 | invalid_request_error | No user message provided | Heerarka Shannon: codsigu qoraal isticmaale ma haysto. |
400 | invalid_request_error | <id> does not accept image input | Sawir ayaa loo diray model open-weight oo la martigeliyay oo aan aqbalin gelinta sawirka. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Qayb cod ama muuqaal ah ayaa loo diray model open-weight oo la martigeliyay. |
400 | invalid_request_error | <id> does not accept response_format | Structured output ayaa laga codsaday model open-weight oo la martigeliyay oo aan haysan. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | JSON schema ayaa loo diray model open-weight oo la martigeliyay oo qaata json_object oo keliya. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Reasoning effort ma aha mid ka mid ah qiimayaasha la liis gareeyay. Model-yada open-weight ee la martigeliyo. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Tirinta token-yada ayaa loo codsaday model ka baxsan model-yada open-weight ee la martigeliyo. |
401 | authentication_error | Missing authentication | Fure API lama dirin. |
401 | authentication_error | Invalid API key | Furaha lama aqoon, waxaa beddelay mid ka cusub, ama waa la meel mariyay. |
404 | not_found_error | Not Found | Jidku ma jiro, tusaale ahaan /v1/embeddings. |
405 | api_error | Method Not Allowed | Jidku wuu jiraa laakiin ma jiro habkan HTTP. |
413 | invalid_request_error | Failed to buffer the request body: … | Jidhka codsigu wuu ka weyn yahay 32 MiB. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Header-ka Content-Type waa maqan yahay ama ma aha application/json. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Field loo baahan yahay waa maqan yahay, sida messages, ama field wuxuu leeyahay nooc JSON qaldan. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Xadka output-ka codsiga wuu ka weyn yahay waxa ka hadhay haraaggaaga. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Flood protection: in ka badan 120 codsi hal daqiiqo gudaheeda akoonkaaga. <n> waa tirada ilbiriqsiyada ilaa daqiiqaddu dhammaato. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 /v1/chat/completions iyo /v1/messages: wicitaannada Shannon Coder ee qorshahaaga ee daaqadda 4-saac ee hadda waa la isticmaalay. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Model-ku hadda waa mashquul. |
500 | server_error | The model backend failed to answer. Please retry. | Model-ku jawaab ma soo saarin. |
500 | server_error | An internal error occurred. Please retry. | Fashil gudaha ah inta codsiga la diyaarinayay. |
502 | api_error | The model backend failed to answer. Please retry. | Model-ku jawaab ma soo saarin. Qoyska Shannon 3 iyo model-yada open-weight ee la martigeliyo. |
503 | api_error | Could not verify your quota right now. Please retry. | Haraaggaaga hadda lama akhrin karin. |
503 | api_error | token counting is temporarily unavailable for this model | Tirinta token-yadu hadda uma diyaarsana model-kan. |
504 | api_error | upstream timed out | Model open-weight oo la martigeliyay wuxuu ka dheeraaday xadka wakhtiga codsi aan stream ahayn. |
Hubinta waxay u socotaa sidan: furaha API, jidhka codsiga, id-ga model-ka, flood protection, haraagga. Codsi leh fure khaldan iyo jidh khaldan sidaas darteed wuxuu soo celiyaa 401. Codsi lagu diido xaalad 4xx lagu ma dallaco.
Haraag iyo flood protection
Codsi kasta si siman ayaa loo bixiyaa: heerar rate ma jiraan, quota API oo gooni ahna ma jirto. Laba shay ayaa weli ku jawaabi kara 429, labaduba nooca rate_limit_error. Fariintu way kala saartaa.
Haraag
Haraaggaagu waa allowance-ka qorshaha ee maanta, kaas oo dib u dejisma saacadda 00:00 UTC, kaddibna credit-kaaga la iibsaday. Chat-ka iyo API-gu waxay ka qaadaan isla haraag.
Codsi kastaa marka hore wuxuu kala dhigaa xadka output-kiisa: max_tokens, ama max_output_tokens /v1/responses, 4,096 marka aadan midna dirin. Marka jawaabtu dhammaato, cadadka la kala dhigay waxaa lagu beddelaa waxa codsigu isticmaalay. Haddii cadadku ku soo galin haraagga hadhay, codsigu wuxuu soo celiyaa Quota exceeded ka hor inta model-ku bilaabin.
Codsiyada isku mar socda mid kastaa wuxuu kala dhigaa cadadkiisa. Codsiyo badan oo isku mar ah oo leh max_tokens sare sidaas darteed waxay ku dhammayn karaan haraagga wakhti yar, xataa marka jawaab kasta gaaban tahay. max_tokens hoose wuxuu kala dhigaa wax yar.
Flood protection
Flood protection wuxuu oggol yahay 120 codsi daqiiqad kasta akoon kasta. Wuxuu tiriyaa akoonka, ma aha furaha, /v1/chat/completions, /v1/responses iyo /v1/messages wada. Daqiiqaddu waxay ku bilaabmaan codsigaaga ugu horreeya.
Codsiga lambarka 121 daqiiqaddaas dhexdeeda wuxuu soo celiyaa Too many requests. Retry in <n>s. wax kumana kacayo. Codsiyada la diiday way tirsan yihiin, sidaas darteed macmiil mar kale diraya sugid la'aan wuxuu ahaanayaa la diiday ilaa daqiiqaddu dhammaato. Sug <n> ilbiriqsi ee fariinta.
Codsiyada isku mar la diro waa lagama diido inay isku mar yihiin. Safka ayay ku sugaan oo isku xigxig ayaa laga jawaabaa.
GET /v1/models iyo endpoint-yada tirinta token-yada lagama tiriyo.
Wax badan oo ku saabsan xadka iyo haraagga, iyo halka laga arko haraaggaaga iyo isticmaalkaaga: Xadad iyo haraag Fure & isticmaal
Waxa dib loo tijaabiyo
Codsi mar kale dir marka isla codsigaas uu guuleysan karo oo keliya. SDK-yada OpenAI iyo Anthropic horeba waxay laba jeer iskood ugu celiyaan jawaabaha 429 iyo 5xx; deji max_retries (maxRetries JavaScript) si aad u beddesho.
| Khalad | Mar kale dir? | Sida |
|---|---|---|
400, 404, 405, 413, 415, 422 | Maya. Marka hore hagaaji codsiga. | Fariintu waxay magacaabaysaa field-ka, model-ka ama input-ka khaldan. |
401 | Maya. Isticmaal fure sax ah. | Samee ama beddel furaha bogga Fure & isticmaal. |
429 Too many requests | Haa, sugid ka dib. | Sug tirada ilbiriqsiyada fariinta ku jirta, kaddib dir isla codsiga. |
429 Quota exceeded | Sidiisa ma ahan. | Hoos u dhig max_tokens, sug dib u dejinta maalinlaha ah saacadda 00:00 UTC, ama ku dar credit. |
429 Shannon Coder call quota reached | Haa, daaqadda xigta. | Daaqadaha waxay bilaabmaan 4 saac kasta laga bilaabo 00:00 UTC. Model kale isla markiiba wuu jawaabayaa. |
429 … temporarily busy | Haa. | Sug dhowr ilbiriqsi, kaddib wakhti dheer isku day kasta oo dambe. |
500, 502, 503 | Haa. | Sug 1 ilbiriqsi, kaddib 2, 4 iyo 8. Jooji dhowr isku day ka dib oo sheeg id-ga codsiga. |
504 | Haa. | U dir iyadoo stream la dejiyay true: xadka wakhtigu wuxuu khuseeyaa jawaabaha aan stream ahayn. |
Wareeg dib-u-tijaabin oo raacaya shaxdan:
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); Khaladaad stream dhexdiisa ah
Stream wuxuu leeyahay xaalad 200 ka bilaabma byte-kiisii ugu horreeyay. Fashil ka dambeeya wuxuu u yimaadaa sida event stream dhexdiisa: chunk leh xubin error /v1/chat/completions, event error /v1/messages, event response.failed ama error /v1/responses. Events-ka xidhitaanka stream-ka weli way raacayaan. Jawaab sidaas ah u aqoon sida fashilantay oo mar kale dir codsiga, sida xaalad 5xx.
Wada-hadal ka dheer context window-ka model-ka sidan ayaa loo sheegaa, iyadoo nooca yahay invalid_request_error iyo code-ka context_length_exceeded. Wada-hadalka soo gaabi ka hor inta aadan mar kale dirin.
Frame-yada saxda ah waxaa lagu sharaxay streaming. Streaming
Id-yada codsiga
Jawaab kasta, khaladaadka ku jira, waxay leedahay header x-request-id. Waa qiimaha aad ku dirtay header-kaaga x-request-id, ama 12 xaraf hexadecimal ah marka aadan dirin. Diiwaangeli, oo ku xus marka aad caawimaad ka codsato codsi.