بازدان بۆ ناوەڕۆک
Çewtî

Çewtî

داواکارییەکی شکستخواردوو کۆدی status ی HTTP و body ی JSON ێک دەگەڕێنێتەوە کە جۆری هەڵە و پەیامی تێدایە. ئەم لاپەڕەیە هەموو status ـەکان لیست دەکات، body ی هەڵەی هەر فۆرماتێکی API نیشان دەدات و دەڵێت کام هەڵە ئەوەندە بەهادارن کە دووبارە بنێردرێنەوە.

SDK ـەکان ئۆبجێکتێکی هەڵە دەهێنن کە کۆدی status و بوارەکانی body هەڵدەگرێت. ئەم داواکارییە ناوی مۆدێلێک دەبات کە بوونی نییە:

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 وەڵام دەداتەوە؛ هەموو endpoint ێکی دیکە بە فۆرماتی OpenAI. لە هەردووکیاندا وردەکارییەکان لە error.type و error.message دان، بۆیە یەک خوێنەر بۆ هەموو endpoint ـەکان بەسە.

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 هەیە: invalid_api_key لەگەڵ 401، request_too_large لەگەڵ 413، context_length_exceeded کاتێک گفتوگۆیەک زۆر درێژ بێت، ئەگینا null یان نەبوو. سەرەتا بەپێی status و error.type بڕیار بدە و code وەک زیادەیەک مامەڵە لەگەڵ بکە.
error.param null لەسەر هەمان هەڵەکانی code هەیە. هەمیشە null.
type string تەنها فۆرماتی Anthropic. هەمیشە error.

جۆرەکانی هەڵە

جۆر Statusـەکان وەسف
invalid_request_error 400, 413, 415, 422 خودی داواکارییەکە هەڵەیە: بوارێک، body، 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 داواکارییەکە دروست بوو و شکستەکە لە لای ئێمەیە. دووبارە بینێرە.

کۆدەکانی 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 ی میوانداریکراو نێردرا کە 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 ی structured لە مۆدێلێکی 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 ئاستی بیرکردنەوە یەکێک نییە لە بەها لیستکراوەکان. مۆدێلە 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: … body ی داواکارییەکە لە 32 MiB گەورەترە.
415 invalid_request_error Expected request with `Content-Type: application/json` header ی Content-Type نییە یان 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: بانگکردنەکانی 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 هەژمارکردنی تۆکن لەم ساتەدا بۆ ئەم مۆدێلە بەردەست نییە.
504 api_error upstream timed out مۆدێلێکی open-weight ی میوانداریکراو لە سنووری کاتی داواکارییەک کە stream نەکراوە زیاتری خایاند.

پشکنینەکان بەم ڕیزبەندییە ئەنجام دەدرێن: کلیلی API، body ی داواکاری، id ی مۆدێل، flood protection، باڵانس. بۆیە داواکارییەک بە کلیلی هەڵە و body ی هەڵە 401 دەگەڕێنێتەوە. داواکارییەک کە بە status ی 4xx ڕەت بکرێتەوە نرخ ناگیرێت.

باڵانس و flood protection

هەموو داواکارییەک یەکسان خزمەت دەکرێت: ئاستی ڕێژە و quota ی API ی جیاواز نییە. هێشتا دوو شت دەتوانن بە 429 وەڵام بدەنەوە، هەردووکیان بە جۆری rate_limit_error. پەیامەکە جیایان دەکاتەوە.

باڵانس

باڵانسەکەت ڕێپێدانی پلانی ئەمڕۆیە، کە لە 00:00 UTC دەست پێدەکاتەوە، و دوای ئەوە کرێدیتی کڕدراوەکەت. Chat و API لە هەمان باڵانس دەخۆن.

هەر داواکارییەک سەرەتا سنووری output ی خۆی ڕادەگرێت: 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 و endpoint ـەکانی هەژمارکردنی تۆکن هەژمار ناکرێن.

زیاتر دەربارەی سنوورەکان و باڵانس، و لە کوێ باڵانس و بەکارهێنانی خۆت ببینیت: سنوور و باڵانس Keys & usage

چی دووبارە بکرێتەوە

داواکارییەک تەنها کاتێک دووبارە بنێرە کە هەمان داواکاری بتوانێت سەرکەوتوو بێت. SDK ـەکانی OpenAI و Anthropic خۆیان پێشتر وەڵامەکانی 429 و 5xx دوو جار دووبارە دەکەنەوە؛ max_retries (maxRetries لە JavaScript) بگۆڕە بۆ گۆڕینی ئەوە.

هەڵە دووبارە بنێرم؟ چۆن
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 ناکرێن.

خولی دووبارەکردنەوە کە ئەم خشتەیە دەگرێتەبەر:

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 دا دێت: chunk ێک بە ئەندامی error لەسەر /v1/chat/completions، ڕووداوی error لەسەر /v1/messages، ڕووداوی response.failed یان error لەسەر /v1/responses. ڕووداوە کۆتاییەکانی stream هێشتا دەگەن. ئەم وەڵامە وەک شکستخواردوو ببینە و داواکارییەکە دووبارە بنێرە، وەک بۆ status ی 5xx.

گفتوگۆیەک کە لە context window ی مۆدێلەکە درێژتر بێت بەم شێوەیە ڕاپۆرت دەکرێت، بە جۆری invalid_request_error و کۆدی context_length_exceeded. گفتوگۆکە کورت بکەرەوە پێش ئەوەی دووبارە بینێریت.

frame ـە وردەکان لەگەڵ streaming باس کراون. Streaming

id ی داواکاری

هەر وەڵامێک، هەڵەکانیش، header ی x-request-id ی هەیە. ئەو بەهایەیە کە لە header ی x-request-id ی خۆتدا ناردووتە، یان 12 پیتی هەژدەیی ئەگەر هیچت نەناردبێت. لۆگی بکە، و کاتێک بۆ داواکارییەک یارمەتی دەخوازیت بینووسە.