Məzmuna keç
Xəta idarəetməsi

Xəta idarəetməsi

Uğursuz olan sorğu HTTP status kodu və xəta tipi ilə mesajı olan JSON gövdəsi qaytarır. Bu səhifə hər statusu siyahıya alır, hər API formatının xəta gövdəsini göstərir və hansı xətaları yenidən göndərməyə dəyər olduğunu bildirir.

SDK-lar status kodunu və gövdənin sahələrini daşıyan xəta obyekti qaldırır. Bu sorğu mövcud olmayan modelin adını göstərir:

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

O, 400 statusunu və bu gövdəni qaytarır:

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

Xəta gövdəsi

İki gövdə var. /v1/messages Anthropic formatında cavab verir; hər digər endpoint OpenAI formatında cavab verir. Hər ikisində təfərrüatlar error.type və error.message daxilindədir, buna görə bir oxuyucu bütün endpoint-lərə xidmət edir.

401 OpenAI formatı
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic formatı
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
Sahə Tip Təsvir
error.type string Xətanın növü. Aşağıda Xəta tiplərinə baxın.
error.message string İnsan üçün cümlə. Aşağıdakı cədvəllərdəki mətnlər <id>, <n> və ya … kimi göstərilən dəyişən hissələrinə qədər sabitdir.
error.code string | null OpenAI formatının bəzi xətalarında olur: 401 ilə invalid_api_key, 413 ilə request_too_large, söhbət çox uzun olduqda context_length_exceeded, əks halda null və ya yoxdur. Əvvəlcə statusa və error.type sahəsinə əsasən qərar verin, code sahəsini isə əlavə hesab edin.
error.param null code ilə eyni xətalarda olur. Həmişə null.
type string Yalnız Anthropic formatı. Həmişə error.

Xəta tipləri

Tip Statuslar Təsvir
invalid_request_error 400, 413, 415, 422 Sorğunun özü yanlışdır: sahə, gövdə, model id-si və ya modelin qəbul etmədiyi giriş. Yenidən göndərməzdən əvvəl sorğunu dəyişin.
authentication_error 401 API açarı yoxdur, tanınmır və ya ləğv edilib.
not_found_error 404 Yol mövcud deyil.
rate_limit_error 429 Balans sorğunu ödəmir, flood protection onu dayandırıb və ya model məşğuldur. Mesaj hansı olduğunu bildirir.
api_error 500, 502, 503, 504 Sorğu düzgün idi, uğursuzluq bizim tərəfdədir. Onu yenidən göndərin.
server_error 500 Sorğu düzgün idi, uğursuzluq bizim tərəfdədir. Onu yenidən göndərin.

Status kodları

Status Tip Mesaj Nə vaxt
400 invalid_request_error Failed to parse the request body as JSON: … Gövdə etibarlı JSON deyil.
400 invalid_request_error unknown model: <id> model dərc edilmiş id deyil. /v1/responses-da model olmadıqda da bu xəta qaytarılır.
400 invalid_request_error No user message provided Shannon səviyyələri: sorğuda istifadəçi mətni yoxdur.
400 invalid_request_error <id> does not accept image input Şəkil girişi olmayan host edilmiş açıq çəkili modelə şəkil göndərilib.
400 invalid_request_error audio and video input are not supported by any hosted model Host edilmiş açıq çəkili modelə audio və ya video hissəsi göndərilib.
400 invalid_request_error <id> does not accept response_format Strukturlaşdırılmış çıxış onu olmayan host edilmiş açıq çəkili modeldən istənilib.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Yalnız json_object qəbul edən host edilmiş açıq çəkili modelə JSON sxemi göndərilib.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Reasoning effort siyahıdakı dəyərlərdən biri deyil. Host edilmiş açıq çəkili modellər.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Token sayma host edilmiş açıq çəkili modellərdən kənar model üçün istənilib.
401 authentication_error Missing authentication API açarı göndərilməyib.
401 authentication_error Invalid API key Açar tanınmır, daha yeni açarla əvəz olunub və ya ləğv edilib.
404 not_found_error Not Found Yol mövcud deyil, məsələn /v1/embeddings.
405 api_error Method Not Allowed Yol mövcuddur, lakin bu HTTP metodu ilə yox.
413 invalid_request_error Failed to buffer the request body: … Sorğu gövdəsi 32 MiB-dan böyükdür.
415 invalid_request_error Expected request with `Content-Type: application/json` Content-Type başlığı yoxdur və ya application/json deyil.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages kimi tələb olunan sahə yoxdur və ya sahənin JSON tipi yanlışdır.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan Sorğunun çıxış limiti balansınızda qalandan böyükdür.
429 rate_limit_error Too many requests. Retry in <n>s. Flood protection: hesabınızdan bir dəqiqədə 120-dən çox sorğu göndərilib. <n> dəqiqənin bitməsinə qədər saniyələrin sayıdır.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan /v1/chat/completions və /v1/messages üzərində shannon-coder-1: planınızın cari 4 saatlıq pəncərə üçün Shannon Coder çağırışları istifadə olunub.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Model bu anda məşğuldur.
500 server_error The model backend failed to answer. Please retry. Model cavab yaratmadı.
500 server_error An internal error occurred. Please retry. Sorğu hazırlanarkən daxili xəta.
502 api_error The model backend failed to answer. Please retry. Model cavab yaratmadı. Shannon 3 ailəsi və host edilmiş açıq çəkili modellər.
503 api_error Could not verify your quota right now. Please retry. Balansınız bu anda oxuna bilmədi.
503 api_error token counting is temporarily unavailable for this model Token sayma bu model üçün bu anda mövcud deyil.
504 api_error upstream timed out Host edilən açıq çəkili model axın olmayan sorğunun vaxt limitindən uzun çəkdi.

Yoxlamalar bu ardıcıllıqla aparılır: API açarı, sorğu gövdəsi, model id-si, flood protection, balans. Buna görə yanlış açarı və yanlış gövdəsi olan sorğu 401 qaytarır. 4xx statusu ilə rədd edilən sorğu hesablanmır.

Balans və flood protection

Hər sorğuya bərabər xidmət göstərilir: sürət səviyyələri yoxdur və ayrıca API kvotası yoxdur. Yenə də iki şey 429 ilə cavab verə bilər, hər ikisi rate_limit_error tipi ilə. Onları mesaj bir-birindən ayırır.

Balans

Balansınız bugünkü plan limitindən (00:00 UTC-də sıfırlanır) və ondan sonra alınmış kreditdən ibarətdir. Çat və API eyni balansdan istifadə edir.

Hər sorğu əvvəlcə çıxış limitini ayırır: max_tokens və ya /v1/responses üzərində max_output_tokens, heç birini göndərməsəniz 4,096. Cavab tamamlandıqda ayrılan məbləğ sorğunun istifadə etdiyi ilə əvəz olunur. Məbləğ qalan balansa sığmırsa, sorğu model başlamazdan əvvəl Quota exceeded qaytarır.

Eyni vaxtda işləyən sorğuların hər biri öz məbləğini ayırır. Buna görə yüksək max_tokens ilə çoxlu paralel sorğu, hər cavab qısa olsa belə, balansı bir anlıq tükədə bilər. Daha kiçik max_tokens daha az ayırır.

Flood protection

Flood protection hesab başına dəqiqədə 120 sorğuya icazə verir. O, /v1/chat/completions, /v1/responses və /v1/messages endpoint-lərini birlikdə, açarı yox, hesabı sayır. Dəqiqə ilk sorğunuzla başlayır.

Həmin dəqiqə daxilində 121-ci sorğu Too many requests. Retry in <n>s. qaytarır və heç nəyə başa gəlmir. Rədd edilən sorğular da sayılır, buna görə gözləmədən yenidən göndərən klient dəqiqə bitənə qədər rədd edilməkdə qalır. Mesajdakı <n> saniyə gözləyin.

Paralel göndərilən sorğular paralel olduqları üçün rədd edilmir. Onlar növbədə gözləyir və növbə ilə cavablanır.

GET /v1/models və token sayma endpoint-ləri sayılmır.

Limitlər və balans haqqında daha çox və öz balansınıza və istifadənizə harada baxmaq barədə: Limitlər və balans Keys & usage

Nəyi təkrar etmək

Sorğunu yalnız eyni sorğu uğurlu ola bildikdə yenidən göndərin. OpenAI və Anthropic SDK-ları 429 və 5xx cavablarını artıq özləri iki dəfə təkrar edir; bunu dəyişmək üçün max_retries (JavaScript-də maxRetries) təyin edin.

Xəta Yenidən göndərilsin? Necə
400, 404, 405, 413, 415, 422 Xeyr. Əvvəlcə sorğunu düzəldin. Mesaj yanlış olan sahəni, modeli və ya girişi göstərir.
401 Xeyr. Etibarlı açar istifadə edin. Açarı Keys & usage səhifəsində yaradın və ya əvəz edin.
429 Too many requests Bəli, gözləmədən sonra. Mesajdakı saniyə qədər gözləyin, sonra eyni sorğunu göndərin.
429 Quota exceeded Olduğu kimi yox. max_tokens dəyərini azaldın, 00:00 UTC-dəki gündəlik sıfırlanmanı gözləyin və ya kredit əlavə edin.
429 Shannon Coder call quota reached Bəli, növbəti pəncərədə. Pəncərələr 00:00 UTC-dən başlayaraq hər 4 saatdan bir başlayır. Başqa model dərhal cavab verir.
429 … temporarily busy Bəli. Bir neçə saniyə gözləyin, sonra hər növbəti cəhddə daha uzun.
500, 502, 503 Bəli. 1 saniyə, sonra 2, 4 və 8 saniyə gözləyin. Bir neçə cəhddən sonra dayanın və sorğu id-sini bildirin.
504 Bəli. Onu stream dəyəri true olmaqla göndərin: vaxt limiti axınsız cavablara tətbiq olunur.

Bu cədvələ uyğun təkrar cəhd dövrəsi:

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)

Axın daxilindəki xətalar

Axının statusu ilk baytdan 200-dür. Bundan sonrakı uğursuzluq axın daxilində hadisə kimi gəlir: /v1/chat/completions üzərində error üzvü olan chunk, /v1/messages üzərində error hadisəsi, /v1/responses üzərində response.failed və ya error hadisəsi. Axının bağlayıcı hadisələri yenə də ardınca gəlir. Belə cavabı uğursuz sayın və sorğunu 5xx statusunda olduğu kimi yenidən göndərin.

Modelin kontekst pəncərəsindən uzun söhbət belə bildirilir, invalid_request_error tipi və context_length_exceeded kodu ilə. Yenidən göndərməzdən əvvəl söhbəti qısaldın.

Dəqiq frame-lər streaming ilə birgə təsvir olunub. Axın

Sorğu id-ləri

Hər cavabda, xətalar daxil, x-request-id başlığı var. Bu, öz x-request-id başlığınızda göndərdiyiniz dəyərdir, heç nə göndərmədikdə isə 12 onaltılıq simvoldur. Onu jurnalda saxlayın və sorğu ilə bağlı kömək istəyərkən qeyd edin.