ናብ ትሕዝቶ ዝለል
ሓጋይ ኣስተዳደር

ሓጋይ ኣስተዳደር

ዝወድቕ ጠለብ 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

ኩነታት 400 ከምኡውን እዚ body ይመልስ፦

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

ናይ ጌጋ body

ክልተ bodies ኣለዉ። /v1/messages ብቅርጺ Anthropic ይመልስ፤ ነፍሲ ወከፍ ካልእ endpoint ብቅርጺ OpenAI ይመልስ። ኣብ ክልቲኦም ዝርዝራት ኣብ error.type ከምኡውን error.message ኣለዉ፣ ስለዚ ሓደ reader ንኩሎም 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"
  }
}
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)

ጌጋታት ኣብ ውሽጢ 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 ፊደላት። መዝግቦ፣ ብዛዕባ ጠለብ ሓገዝ ክትሓትት ከሎ ድማ ጠቐስዎ።