ወደ ይዘቱ እለፍ
ስህተት አስተዳደር

ስህተት አስተዳደር

የሚከሽፍ ጥያቄ 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

status 400 እና ይህን body ይመልሳል፦

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}

የስህተት አካል

ሁለት አይነት body አሉ። /v1/messages በAnthropic ፎርማት ይመልሳል፤ ሌሎች endpoints ሁሉ በOpenAI ፎርማት ይመልሳሉ። በሁለቱም ዝርዝሩ በerror.type እና በerror.message ውስጥ ነው፣ ስለዚህ አንድ አንባቢ ለሁሉም endpoints ይበቃል።

401 OpenAI ፎርማት
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic ፎርማት
{
  "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)

በ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 የሄክሳዴሲማል ቁምፊዎች። ይመዝግቡት፣ እና ስለ ጥያቄ እርዳታ ሲጠይቁ ይጥቀሱት።