Fouthantering
'n Versoek wat misluk, gee 'n HTTP-statuskode en 'n JSON-liggaam met 'n foutipe en 'n boodskap terug. Hierdie bladsy lys elke status, wys die foutliggaam van elke API-formaat en sê watter foute die moeite werd is om weer te stuur.
Die SDK's gooi 'n foutobjek wat die statuskode en die velde van die liggaam dra. Hierdie versoek noem 'n model wat nie bestaan nie:
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"}]
}' Dit gee status 400 en hierdie liggaam terug:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Foutliggaam
Daar is twee liggame. /v1/messages antwoord in die Anthropic-formaat; elke ander eindpunt antwoord in die OpenAI-formaat. In albei is die besonderhede in error.type en error.message, so een leser bedien alle eindpunte.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Veld | Tipe | Beskrywing |
|---|---|---|
error.type | string | Die soort fout. Sien Foutipes hieronder. |
error.message | string | 'n Sin vir 'n mens. Die tekste in die tabelle hieronder is stabiel tot op hul veranderlike dele, gewys as <id>, <n> of …. |
error.code | string | null | Teenwoordig op sommige foute van die OpenAI-formaat: invalid_api_key met 401, request_too_large met 413, context_length_exceeded wanneer 'n gesprek te lank is, anders null of afwesig. Besluit eers op die status en error.type en behandel code as 'n ekstra. |
error.param | null | Teenwoordig op dieselfde foute as code. Altyd null. |
type | string | Slegs Anthropic-formaat. Altyd error. |
Foutipes
| Tipe | Statusse | Beskrywing |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Die versoek self is verkeerd: 'n veld, die liggaam, die model-id of 'n inset wat die model nie neem nie. Verander die versoek voordat jy dit weer stuur. |
authentication_error | 401 | Die API-sleutel ontbreek, is onbekend of herroep. |
not_found_error | 404 | Die pad bestaan nie. |
rate_limit_error | 429 | Die balans dek nie die versoek nie, vloedbeskerming het dit gestop, of die model is besig. Die boodskap sê watter. |
api_error | 500, 502, 503, 504 | Die versoek was in orde en die mislukking is aan ons kant. Stuur dit weer. |
server_error | 500 | Die versoek was in orde en die mislukking is aan ons kant. Stuur dit weer. |
Statuskodes
| Status | Tipe | Boodskap | Wanneer |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Die liggaam is nie geldige JSON nie. |
400 | invalid_request_error | unknown model: <id> | model is nie 'n gepubliseerde id nie. Op /v1/responses ook wanneer model ontbreek. |
400 | invalid_request_error | No user message provided | Shannon-vlakke: die versoek bevat geen gebruikersteks nie. |
400 | invalid_request_error | <id> does not accept image input | 'n Beeld is na 'n gehuisveste oopgewig-model gestuur sonder beeldinset. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | 'n Oudio- of video-deel is na 'n gehuisveste oopgewig-model gestuur. |
400 | invalid_request_error | <id> does not accept response_format | Gestruktureerde uitvoer is gevra van 'n gehuisveste oopgewig-model sonder dit. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | 'n JSON-skema is na 'n gehuisveste oopgewig-model gestuur wat slegs json_object neem. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Die redeneringspoging is nie een van die gelyste waardes nie. Gehuisveste oopgewig-modelle. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Tokentelling is gevra vir 'n model buite die gehuisveste oopgewig-modelle. |
401 | authentication_error | Missing authentication | Geen API-sleutel is gestuur nie. |
401 | authentication_error | Invalid API key | Die sleutel is onbekend, is deur 'n nuwer een vervang, of is herroep. |
404 | not_found_error | Not Found | Die pad bestaan nie, byvoorbeeld /v1/embeddings. |
405 | api_error | Method Not Allowed | Die pad bestaan maar nie met hierdie HTTP-metode nie. |
413 | invalid_request_error | Failed to buffer the request body: … | Die versoekliggaam is groter as 32 MiB. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Die Content-Type-header ontbreek of is nie application/json nie. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | 'n Verpligte veld ontbreek, soos messages, of 'n veld het die verkeerde JSON-tipe. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Die versoek se uitvoerlimiet is groter as wat van jou balans oor is. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Vloedbeskerming: meer as 120 versoeke in een minuut op jou rekening. <n> is die aantal sekondes tot die minuut eindig. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 op /v1/chat/completions en /v1/messages: jou plan se Shannon Coder-oproepe vir die huidige 4-uur-venster is opgebruik. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Die model is op hierdie oomblik besig. |
500 | server_error | The model backend failed to answer. Please retry. | Die model het nie 'n antwoord gelewer nie. |
500 | server_error | An internal error occurred. Please retry. | 'n Interne mislukking terwyl die versoek voorberei is. |
502 | api_error | The model backend failed to answer. Please retry. | Die model het nie 'n antwoord gelewer nie. Shannon 3-familie en gehuisveste oopgewig-modelle. |
503 | api_error | Could not verify your quota right now. Please retry. | Jou balans kon op hierdie oomblik nie gelees word nie. |
503 | api_error | token counting is temporarily unavailable for this model | Tokentelling is op hierdie oomblik nie vir hierdie model beskikbaar nie. |
504 | api_error | upstream timed out | 'n Gehuisveste oopgewig-model het langer as die tydlimiet geneem van 'n versoek wat nie gestroom word nie. |
Kontroles loop in hierdie volgorde: API-sleutel, versoekliggaam, model-id, vloedbeskerming, balans. 'n Versoek met 'n verkeerde sleutel en 'n verkeerde liggaam gee dus 401 terug. 'n Versoek wat met 'n 4xx-status geweier word, word nie gehef nie.
Balans en vloedbeskerming
Elke versoek word gelyk bedien: daar is geen koersvlakke en geen aparte API-kwota nie. Twee dinge kan steeds 429 antwoord, albei met die tipe rate_limit_error. Die boodskap onderskei hulle.
Balans
Jou balans is vandag se plan-toelaat, wat om 00:00 UTC herstel, en daarna jou gekoopte krediet. Klets en die API trek van dieselfde balans af.
Elke versoek sit eers sy uitvoerlimiet opsy: max_tokens, of max_output_tokens op /v1/responses, 4,096 wanneer jy nie een stuur nie. Wanneer die antwoord voltooi is, word die bedrag wat opsy gesit is vervang deur wat die versoek gebruik het. As die bedrag nie in die balans pas wat oor is nie, gee die versoek Quota exceeded terug voordat die model begin.
Versoeke wat gelyktydig loop, sit elk hul eie bedrag opsy. Baie parallelle versoeke met 'n hoë max_tokens kan dus die balans vir 'n oomblik opgebruik, selfs wanneer elke antwoord kort is. 'n Laer max_tokens sit minder opsy.
Vloedbeskerming
Vloedbeskerming laat 120 versoeke per minuut per rekening toe. Dit tel die rekening, nie die sleutel nie, oor /v1/chat/completions, /v1/responses en /v1/messages saam. Die minuut begin met jou eerste versoek.
Versoek nommer 121 binne daardie minuut gee Too many requests. Retry in <n>s. terug en kos niks. Geweierde versoeke tel ook, so 'n kliënt wat weer stuur sonder om te wag, bly geweier totdat die minuut verby is. Wag die <n> sekondes uit die boodskap.
Versoeke wat parallel gestuur word, word nie geweier omdat hulle parallel is nie. Hulle wag in 'n tou en word om die beurt beantwoord.
GET /v1/models en die tokentel-eindpunte word nie getel nie.
Meer oor limiete en balans, en waar om jou eie balans en gebruik te sien: Perke en balans Sleutels en gebruik
Wat om weer te probeer
Stuur 'n versoek net weer wanneer dieselfde versoek kan slaag. Die OpenAI- en Anthropic-SDK's probeer 429- en 5xx-antwoorde reeds twee keer self weer; stel max_retries (maxRetries in JavaScript) om dit te verander.
| Fout | Weer stuur? | Hoe |
|---|---|---|
400, 404, 405, 413, 415, 422 | Nee. Maak eers die versoek reg. | Die boodskap noem die veld, die model of die inset wat verkeerd is. |
401 | Nee. Gebruik 'n geldige sleutel. | Skep of vervang die sleutel op die bladsy Sleutels en gebruik. |
429 Too many requests | Ja, ná die wag. | Wag die aantal sekondes in die boodskap, stuur dan dieselfde versoek. |
429 Quota exceeded | Nie soos dit is nie. | Verlaag max_tokens, wag vir die daaglikse herstel om 00:00 UTC, of voeg krediet by. |
429 Shannon Coder call quota reached | Ja, in die volgende venster. | Die vensters begin elke 4 uur vanaf 00:00 UTC. 'n Ander model antwoord dadelik. |
429 … temporarily busy | Ja. | Wag 'n paar sekondes, dan langer by elke verdere poging. |
500, 502, 503 | Ja. | Wag 1 sekonde, dan 2, 4 en 8. Hou op ná 'n paar pogings en rapporteer die versoek-id. |
504 | Ja. | Stuur dit met stream op true: die tydlimiet geld vir antwoorde wat nie gestroom word nie. |
'n Herpoging-lus wat hierdie tabel volg:
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); Foute binne 'n stroom
'n Stroom het status 200 vanaf sy eerste byte. 'n Mislukking daarna kom as 'n gebeurtenis binne die stroom aan: 'n brokkie met 'n error-lid op /v1/chat/completions, 'n error-gebeurtenis op /v1/messages, 'n response.failed- of error-gebeurtenis op /v1/responses. Die sluitingsgebeurtenisse van die stroom volg steeds. Beskou so 'n antwoord as misluk en stuur die versoek weer, soos vir 'n 5xx-status.
'n Gesprek wat langer is as die model se konteksvenster, word op hierdie manier gerapporteer, met die tipe invalid_request_error en die kode context_length_exceeded. Kort die gesprek in voordat jy dit weer stuur.
Die presiese rame word saam met streaming beskryf. Stroming
Versoek-id's
Elke antwoord, foute ingesluit, het 'n x-request-id-header. Dit is die waarde wat jy in jou eie x-request-id-header gestuur het, of 12 heksadesimale karakters wanneer jy niks gestuur het nie. Teken dit aan, en haal dit aan wanneer jy hulp met 'n versoek vra.