Мазмунга өтүү
Ката иштетүү

Ката иштетүү

Ишке ашпаган сурам 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 Сүрөт кириши жок хостингдеги ачык салмактуу моделге сүрөт жөнөтүлдү.
400 invalid_request_error audio and video input are not supported by any hosted model Хостингдеги ачык салмактуу моделге аудио же видео бөлүгү жөнөтүлдү.
400 invalid_request_error <id> does not accept response_format Структураланган чыгыш аны колдобогон хостингдеги ачык салмактуу моделден суралды.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object json_object гана кабыл алган хостингдеги ачык салмактуу моделге JSON схемасы жөнөтүлдү.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Reasoning аракети тизмектеги маанилердин бири эмес. Хостингдеги ачык салмактуу моделдер.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Токен саноо хостингдеги ачык салмактуу моделдерден тышкаркы модель үчүн суралган.
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 үй-бүлөсү жана хостингдеги ачык салмактуу моделдер.
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 Хостингдеги ачык салмактуу модель стримдебеген сурамдын убакыт чегинен узагыраак убакыт алды.

Текшерүүлөр ушул тартипте жүрөт: 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'тери эсептелбейт.

Чектөөлөр жана баланс жөнүндө көбүрөөк, ошондой эле өз балансыңыз менен колдонууңузду кайдан көрүүгө болору: Чектөөлөр жана баланс Ачкычтар жана колдонуу

Эмнени кайра жөнөтүү керек

Сурамды ошол эле сурам ийгиликтүү болуши мүмкүн болгондо гана кайра жөнөтүңүз. 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. Кайра жөнөтүүдөн мурун сүйлөшүүнү кыскартыңыз.

Так фреймдер стриминг бетинде сүрөттөлгөн. Стриминг

Сурам id'лери

Ар бир жооп, каталар да, x-request-id башына ээ. Бул сиз өз x-request-id башыңызда жөнөткөн маани, же эч нерсе жөнөтпөсөңүз 12 он алтылык белги. Аны журналга жазыңыз жана сурам боюнча жардам сурасаңыз көрсөтүңүз.