Гузариш ба мундариҷа
Идораи хатогиҳо

Идораи хатогиҳо

Дархосте, ки ноком мешавад, рамзи ҳолати 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 ҳозир аст: 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 Худи дархост нодуруст аст: майдон, бадан, id-и модел ё вурудие, ки модел қабул намекунад. Пеш аз бори дигар фиристодан дархостро тағйир диҳед.
authentication_error 401 Калиди API намерасад, ношинос аст ё бекор шудааст.
not_found_error 404 Роҳ вуҷуд надорад.
rate_limit_error 429 Баланс дархостро фаро намегирад, ҳифз аз дархостҳои аз ҳад зиёд онро боздошт, ё модел банд аст. Паём мегӯяд, ки кадом.
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-и хостшуда фиристода шуд, ки вуруди тасвирро надорад.
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 ба модели open-weight-и хостшуда фиристода шуд, ки танҳо json_object-ро қабул мекунад.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Сатҳи кӯшиши reasoning яке аз қиматҳои номбаршуда нест. Моделҳои 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 намерасад ё 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. Ҳифз аз дархостҳои аз ҳад зиёд: беш аз 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-и хостшуда аз маҳдудияти вақти дархости бе streaming бештар вақт гирифт.

Санҷишҳо бо ин тартиб иҷро мешаванд: калиди API, бадани дархост, id-и модел, ҳифз аз дархостҳои аз ҳад зиёд, баланс. Бинобар ин дархост бо калиди нодуруст ва бадани нодуруст 401 бармегардонад. Дархосте, ки бо ҳолати 4xx рад карда мешавад, ҳисоб карда намешавад.

Баланс ва ҳифз аз дархостҳои аз ҳад зиёд

Ҳар дархост баробар хидмат карда мешавад: сатҳҳои меъёр ва квотаи алоҳидаи API вуҷуд надорад. Ду чиз ҳамоно метавонанд 429 ҷавоб диҳанд, ҳарду бо навъи rate_limit_error. Паём онҳоро аз ҳам фарқ мекунад.

Баланс

Балансатон меъёри ҳаррӯзаи нақша аст, ки соати 00:00 UTC аз нав оғоз мешавад, ва пас аз он кредити харидашудаатон. Чат ва API аз ҳамон як баланс сарф мекунанд.

Ҳар дархост аввал ҳадди баромади худро ҷудо мекунад: max_tokens, ё max_output_tokens дар /v1/responses, 4,096 вақте ки ҳеҷ яке фиристода нашудааст. Вақте ки ҷавоб тамом мешавад, миқдори ҷудошуда бо он чи дархост истифода кард, иваз карда мешавад. Агар миқдор ба балансе, ки мондааст, ҷо нашавад, дархост пеш аз оғози модел Quota exceeded бармегардонад.

Дархостҳое, ки ҳамзамон иҷро мешаванд, ҳар кадом миқдори худро ҷудо мекунанд. Бинобар ин бисёр дархостҳои мувозӣ бо max_tokens-и баланд метавонанд балансро лаҳзае тамом кунанд, ҳатто агар ҳар ҷавоб кӯтоҳ бошад. max_tokens-и камтар камтар ҷудо мекунад.

Ҳифз аз дархостҳои аз ҳад зиёд

Ҳифз аз дархостҳои аз ҳад зиёд 120 дархост дар як дақиқа барои ҳар аккаунтро иҷозат медиҳад. Он аккаунтро ҳисоб мекунад, на калидро, дар /v1/chat/completions, /v1/responses ва /v1/messages якҷоя. Дақиқа бо аввалин дархости шумо оғоз мешавад.

Дархости рақами 121 дар дохили он дақиқа Too many requests. Retry in <n>s. бармегардонад ва ҳеҷ арзише надорад. Дархостҳои рад кардашуда низ ҳисоб мешаванд, бинобар ин клиенте, ки бе интизорӣ бори дигар мефиристад, то анҷоми дақиқа рад шуда мемонад. <n> сонияро аз паём интизор шавед.

Дархостҳое, ки мувозӣ фиристода мешаванд, барои мувозӣ будан рад карда намешаванд. Онҳо дар навбат меистанд ва ба навбат ҷавоб дода мешаванд.

GET /v1/models ва endpoint-ҳои ҳисоби токен ҳисоб карда намешаванд.

Бештар дар бораи маҳдудиятҳо ва баланс ва ин ки балансу истифодаи худро дар куҷо дидан мумкин аст: Маҳдудиятҳо ва баланс Калидҳо ва истифода

Чиро такрор кардан лозим

Дархостро танҳо вақте бори дигар фиристед, ки ҳамон дархост муваффақ шуда метавонад. SDK-ҳои OpenAI ва Anthropic ҷавобҳои 429 ва 5xx-ро аллакай худашон ду бор такрор мекунанд; барои тағйир додани ин max_retries-ро (maxRetries дар JavaScript) муқаррар кунед.

Хатогӣ Бори дигар фиристем? Чӣ тавр
400, 404, 405, 413, 415, 422 Не. Аввал дархостро ислоҳ кунед. Паём майдон, модел ё вурудеро, ки нодуруст аст, номбар мекунад.
401 Не. Калиди дуруст истифода баред. Калидро дар саҳифаи Калидҳо ва истифода созед ё иваз кунед.
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 гузошта шудааст, фиристед: маҳдудияти вақт ба ҷавобҳои бе streaming татбиқ мешавад.

Ҳалқаи такрор, ки ин ҷадвалро пайравӣ мекунад:

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 дорад. Нокомӣ пас аз он ҳамчун рӯйдод дар дохили ҷараён меояд: чанк бо узви error дар /v1/chat/completions, рӯйдоди error дар /v1/messages, рӯйдоди response.failed ё error дар /v1/responses. Рӯйдодҳои анҷомдиҳандаи ҷараён ҳамоно пайравӣ мекунанд. Чунин ҷавобро ноком ҳисоб кунед ва дархостро бори дигар фиристед, мисли ҳолати 5xx.

Гуфтугӯе, ки аз равзанаи контексти модел дарозтар аст, ҳамин тавр хабар дода мешавад, бо навъи invalid_request_error ва рамзи context_length_exceeded. Гуфтугӯро пеш аз бори дигар фиристодан кӯтоҳ кунед.

Фреймҳои дақиқ бо streaming тавсиф шудаанд. Стриминг

Id-ҳои дархост

Ҳар ҷавоб, аз ҷумла хатогиҳо, сарлавҳаи x-request-id дорад. Он қимати дар сарлавҳаи x-request-id-и худатон фиристодаатон аст, ё 12 аломати шонздаҳӣ вақте ки чизе нафиристодед. Онро сабт кунед ва ҳангоми дархости кӯмак дар бораи дархост қайд кунед.