منځپانګې ته ټوپ ووهئ
د تېروتنې اداره کول

د تېروتنې اداره کول

هغه غوښتنه چې ناکامه شي HTTP د حالت کوډ او د JSON بدنه د تېروتنې ډول او پیغام سره بیرته ورکوي. دا پاڼه هر حالت لیست کوي، د هر API بڼې د تېروتنې بدنه ښيي او وايي چې کومې تېروتنې د بیا لیږلو ارزښت لري.

SDKs د تېروتنې څیز راپورته کوي چې د حالت کوډ او د بدنې ساحې لري. دا غوښتنه هغه ماډل نوموي چې نشته:

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 او دا بدنه بیرته ورکوي:

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

د تېروتنې بدنه

دوه بدنې شته. /v1/messages په Anthropic بڼه ځواب ورکوي؛ هر بل endpoint په 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 یا نشته. لومړی په حالت او error.type پریکړه وکړئ او code اضافي وګڼئ.
error.param null په هماغو تېروتنو کې شتون لري لکه code. تل null.
type string یوازې د Anthropic بڼه. تل error.

د تېروتنو ډولونه

ډول حالتونه تشریح
invalid_request_error 400, 413, 415, 422 پخپله غوښتنه غلطه ده: یوه ساحه، بدنه، د ماډل id یا هغه input چې ماډل یې نه مني. مخکې له بیا لیږلو غوښتنه بدله کړئ.
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: … بدنه معتبر 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 ماډل ته ولیږل شو چې انځور input نه لري.
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 جوړښت لرونکی output د هغه کوربه شوي open-weight ماډل څخه وغوښتل شو چې نه لري.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object JSON schema هغه کوربه شوي open-weight ماډل ته ولیږل شو چې یوازې json_object مني.
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> د ټوکنونو شمېرنه د هغه ماډل لپاره وغوښتل شوه چې د کوربه شوو 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 میتود سره نه.
413 invalid_request_error Failed to buffer the 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: … اړینه ساحه نشته، لکه messages، یا یوه ساحه د JSON غلط ډول لري.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan د غوښتنې د output حد د هغه څه څخه لوی دی چې ستاسو له بیلانس څخه پاتې دي.
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 کې: ستاسو د پلان د اوسنۍ 4 ساعتې کړکۍ Shannon Coder calls کارول شوي.
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 د ټوکنونو شمېرنه پدې شیبه د دې ماډل لپاره شتون نه لري.
504 api_error upstream timed out کوربه شوي open-weight ماډل د هغې غوښتنې د وخت حد څخه ډیر وخت واخیست چې stream نه وه.

چکونه په دې ترتیب چلیږي: API کیلي، د غوښتنې بدنه، د ماډل id، flood protection، بیلانس. هغه غوښتنه چې غلطه کیلي او غلطه بدنه لري نو 401 بیرته ورکوي. هغه غوښتنه چې د 4xx حالت سره رد شي بیل نه کیږي.

بیلانس او flood protection

هره غوښتنه برابره خدمت کیږي: هیڅ rate کچې نشته او هیڅ جلا API کوټه نشته. دوه شیان بیا هم کولی شي 429 ځواب کړي، دواړه د rate_limit_error ډول سره. پیغام یې سره جلا کوي.

بیلانس

ستاسو بیلانس د نن ورځې د پلان اجازه ده، چې په 00:00 UTC بیا ټاکل کیږي، او وروسته له هغې ستاسو اخیستل شوی کریډیټ. چیټ او API له هماغه بیلانس اخلي.

هره غوښتنه لومړی خپل د output حد ساتي: max_tokens، یا په /v1/responses کې max_output_tokens، 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 او د ټوکنونو شمېرنې endpoints نه شمیرل کیږي.

د حدونو او بیلانس په اړه نور، او هغه ځای چیرته چې خپل بیلانس او usage وګورئ: حدونه او بیلانس کیلي او کارونه

څه بیا هڅه کول

غوښتنه یوازې هغه وخت بیا ولیږئ کله چې هماغه غوښتنه بریالۍ کیدی شي. OpenAI او Anthropic SDKs لا دمخه 429 او 5xx ځوابونه دوه ځله پخپله بیا هڅه کوي؛ د بدلولو لپاره max_retries (په JavaScript کې maxRetries) وټاکئ.

تېروتنه بیا لیږل؟ څنګه
400, 404, 405, 413, 415, 422 نه. لومړی غوښتنه سمه کړئ. پیغام هغه ساحه، ماډل یا input نوموي چې غلط دی.
401 نه. معتبره کیلي وکاروئ. کیلي د Keys & usage په پاڼه کې جوړه یا بدله کړئ.
429 Too many requests هو، وروسته له انتظاره. د پیغام د ثانیو شمیر انتظار وکړئ، بیا هماغه غوښتنه ولیږئ.
429 Quota exceeded داسې نه. max_tokens ټیټ کړئ، د 00:00 UTC ورځني بیا ټاکلو ته انتظار وکړئ، یا کریډیټ اضافه کړئ.
429 Shannon Coder call quota reached هو، په راتلونکې کړکۍ کې. کړکۍ هر 4 ساعته له 00:00 UTC پیلیږي. بل ماډل سمدلاسه ځواب ورکوي.
429 … temporarily busy هو. څو ثانیې انتظار وکړئ، بیا په هرې نورې هڅې کې اوږد.
500, 502, 503 هو. 1 ثانیه انتظار وکړئ، بیا 2، 4 او 8. وروسته له څو هڅو ودرېږئ او د غوښتنې id راپور کړئ.
504 هو. دا د stream سره چې په true ټاکل شوی ولیږئ: د وخت حد په هغو ځوابونو پلي کیږي چې stream نه وي.

د بیا هڅې 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 له لومړي بایټ څخه حالت 200 لري. له هغې وروسته ناکامي د stream دننه د رخداد په توګه رارسیږي: په /v1/chat/completions کې د error غړي سره chunk، په /v1/messages کې error رخداد، په /v1/responses کې response.failed یا error رخداد. د stream بندیدو رخدادونه بیا هم ورپسې راځي. داسې ځواب ناکام وګڼئ او غوښتنه بیا ولیږئ، لکه د 5xx حالت لپاره.

ګفتګه چې د ماډل له context window څخه اوږده وي پدې ډول راپور کیږي، د ډول invalid_request_error او کوډ context_length_exceeded سره. ګفتګه مخکې له بیا لیږلو لنډه کړئ.

دقیق frames د streaming سره بیان شوي. جریان

د غوښتنې id ګانې

هر ځواب، تېروتنې په ګډون، x-request-id header لري. دا هغه ارزښت دی چې تاسو په خپل x-request-id header کې لیږلی، یا 12 هیکساډیسیمل توري کله چې تاسو هیڅ نه وي لیږلی. دا ثبت کړئ، او کله چې د غوښتنې په اړه مرسته غواړئ یادونه یې وکړئ.