Мазмұнға өту
Қателерді өңдеу

Қателерді өңдеу

Сәтсіз аяқталған сұрау HTTP мәртебе кодын және қате түрі мен хабарламасы бар JSON денесін қайтарады. Бұл бетте әр мәртебе тізімделген, әр API форматының қате денесі көрсетілген және қай қателерді қайта жіберуге тұратыны айтылған.

SDK-лар мәртебе кодын және дене өрістерін алып жүретін қате нысанын шығарады. Бұл сұрау жоқ модельді атайды:

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 ішінде, сондықтан бір оқушы барлық 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 форматының кейбір қателерінде болады: 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-і немесе модель қабылдамайтын кіріс. Қайта жібермес бұрын сұрауды өзгертіңіз.
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 Сурет кірісі жоқ hosted open-weight модельге сурет жіберілді.
400 invalid_request_error audio and video input are not supported by any hosted model Hosted open-weight модельге аудио немесе бейне бөлігі жіберілді.
400 invalid_request_error <id> does not accept response_format Құрылымдалған шығыс оны қолдамайтын hosted open-weight модельден сұралды.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Тек json_object қабылдайтын hosted open-weight модельге JSON схемасы жіберілді.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Пайымдау күші тізімдегі мәндердің бірі емес. Hosted open-weight модельдер.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Токен санау hosted 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 тақырыбы жоқ немесе 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. Flood protection: аккаунтыңызда бір минутта 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 отбасы және hosted 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 Hosted open-weight модель стримсіз сұрау уақыт шегінен ұзақ уақыт алды.

Тексерулер мына ретпен орындалады: API кілті, сұрау денесі, модель id-і, flood protection, баланс. Сондықтан қате кілті және қате денесі бар сұрау 401 қайтарады. 4xx мәртебесімен қабылданбаған сұрау үшін ақы алынбайды.

Баланс және flood protection

Әр сұрау тең қызмет көрсетіледі: жиілік деңгейлері де, жеке API квотасы да жоқ. Дегенмен екі жағдай 429 қайтара алады, екеуі де rate_limit_error түрімен. Оларды хабарлама ажыратады.

Баланс

Балансыңыз — 00:00 UTC уақытында жаңаратын бүгінгі жоспар лимиті, ал одан кейін сатып алынған кредит. Чат пен API бір балансты пайдаланады.

Әр сұрау алдымен өзінің шығыс шегін бөлек сақтайды: 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 және токен санау endpoint-тері есептелмейді.

Шектеулер мен баланс туралы толығырақ және өз балансыңыз бен қолдануыңызды қайдан көру керек: Шектеулер және баланс Keys & usage

Нені қайталау керек

Сұрауды тек сол сұрау сәтті болуы мүмкін болғанда ғана қайта жіберіңіз. OpenAI және Anthropic SDK-лары 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 етіп жіберіңіз: уақыт шегі стримсіз жауаптарға қолданылады.

Осы кестені ұстанатын қайталау циклі:

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)

Стрим ішіндегі қателер

Стримнің мәртебесі бірінші байттан бастап 200. Одан кейінгі ақау стрим ішіндегі оқиға ретінде келеді: /v1/chat/completions бойынша error мүшесі бар бөлік, /v1/messages бойынша error оқиғасы, /v1/responses бойынша response.failed немесе error оқиғасы. Стримнің жабушы оқиғалары бәрібір артынан келеді. Мұндай жауапты сәтсіз деп санап, 5xx мәртебесіндегідей сұрауды қайта жіберіңіз.

Модельдің контекст терезесінен ұзын сөйлесу осылай хабарланады, invalid_request_error түрімен және context_length_exceeded кодымен. Қайта жібермес бұрын сөйлесуді қысқартыңыз.

Нақты кадрлар streaming бөлімінде сипатталған. Стриминг

Сұрау id-лері

Әр жауапта, қателерді қоса, x-request-id тақырыбы бар. Ол өз x-request-id тақырыбыңызда жіберген мән, ал ештеңе жібермесеңіз 12 оналтылық таңба. Оны журналға жазыңыз және сұрау бойынша көмек сұрағанда келтіріңіз.