İçeriğe geç
Hata yönetimi

Hata yönetimi

Başarısız olan bir istek, bir HTTP durum kodu ve bir hata türü ile mesaj içeren bir JSON gövdesi döndürür. Bu sayfa her durumu listeler, her API biçiminin hata gövdesini gösterir ve hangi hataların yeniden göndermeye değdiğini söyler.

SDK'lar, durum kodunu ve gövdenin alanlarını taşıyan bir hata nesnesi üretir. Bu istek, var olmayan bir modelin adını verir:

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 durumunu ve şu gövdeyi döndürür:

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

Hata gövdesi

İki gövde vardır. /v1/messages Anthropic biçiminde yanıt verir; diğer her uç nokta OpenAI biçiminde yanıt verir. İkisinde de ayrıntılar error.type ve error.message içindedir; bu yüzden tek bir okuyucu tüm uç noktalara hizmet eder.

401 OpenAI biçimi
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Anthropic biçimi
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
Alan Tür Açıklama
error.type string Hatanın türü. Aşağıdaki Hata türleri bölümüne bakın.
error.message string Bir insan için bir cümle. Aşağıdaki tablolardaki metinler, <id>, <n> veya … olarak gösterilen değişken kısımları dışında kararlıdır.
error.code string | null OpenAI biçimindeki bazı hatalarda bulunur: 401 ile invalid_api_key, 413 ile request_too_large, bir konuşma çok uzun olduğunda context_length_exceeded; diğer durumlarda null veya yok. Önce durum koduna ve error.type değerine göre karar verin ve code alanını ek bilgi sayın.
error.param null code ile aynı hatalarda bulunur. Her zaman null.
type string Yalnızca Anthropic biçiminde. Her zaman error.

Hata türleri

Tür Durumlar Açıklama
invalid_request_error 400, 413, 415, 422 İsteğin kendisi yanlış: bir alan, gövde, model kimliği veya modelin kabul etmediği bir girdi. Tekrar göndermeden önce isteği değiştirin.
authentication_error 401 API anahtarı eksik, bilinmiyor veya iptal edilmiş.
not_found_error 404 Yol mevcut değil.
rate_limit_error 429 Bakiye isteği karşılamıyor, flood koruması durdurdu veya model meşgul. Mesaj hangisi olduğunu söyler.
api_error 500, 502, 503, 504 İstek düzgündü ve hata bizim tarafımızda. Tekrar gönderin.
server_error 500 İstek düzgündü ve hata bizim tarafımızda. Tekrar gönderin.

Durum kodları

Durum Tür Mesaj Ne zaman
400 invalid_request_error Failed to parse the request body as JSON: … Gövde geçerli bir JSON değil.
400 invalid_request_error unknown model: <id> model yayımlanmış bir kimlik değil. /v1/responses üzerinde model eksik olduğunda da.
400 invalid_request_error No user message provided Shannon katmanları: istekte kullanıcı metni yok.
400 invalid_request_error <id> does not accept image input Görsel girdisi olmayan host edilen bir açık ağırlıklı modele görsel gönderildi.
400 invalid_request_error audio and video input are not supported by any hosted model Host edilen bir açık ağırlıklı modele ses veya video parçası gönderildi.
400 invalid_request_error <id> does not accept response_format Yapılandırılmış çıktısı olmayan, host edilen bir açık ağırlıklı modelden yapılandırılmış çıktı istendi.
400 invalid_request_error <id> does not accept response_format json_schema; use json_object Yalnızca json_object kabul eden, host edilen bir açık ağırlıklı modele JSON şeması gönderildi.
400 invalid_request_error unknown reasoning effort '<value>'; expected off, low, medium or high Akıl yürütme çabası listelenen değerlerden biri değil. Host edilen açık ağırlıklı modeller.
400 invalid_request_error count_tokens is available for the hosted open models; unknown model: <id> Host edilen açık ağırlıklı modeller dışındaki bir model için token sayımı istendi.
401 authentication_error Missing authentication API anahtarı gönderilmedi.
401 authentication_error Invalid API key Anahtar bilinmiyor, daha yenisiyle değiştirilmiş veya iptal edilmiş.
404 not_found_error Not Found Yol mevcut değil, örneğin /v1/embeddings.
405 api_error Method Not Allowed Yol mevcut ama bu HTTP yöntemiyle değil.
413 invalid_request_error Failed to buffer the request body: … İstek gövdesi 32 MiB'dan büyük.
415 invalid_request_error Expected request with `Content-Type: application/json` Content-Type başlığı eksik veya application/json değil.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages gibi zorunlu bir alan eksik veya bir alanın JSON türü yanlış.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan İsteğin çıktı sınırı, bakiyenizde kalandan büyük.
429 rate_limit_error Too many requests. Retry in <n>s. Flood koruması: hesabınızda bir dakikada 120'den fazla istek. <n>, dakikanın bitmesine kalan saniye sayısıdır.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan /v1/chat/completions ve /v1/messages üzerinde shannon-coder-1: planınızın geçerli 4 saatlik penceredeki Shannon Coder çağrıları tükendi.
429 rate_limit_error Shannon routes are temporarily busy. Please retry. Model şu anda meşgul.
500 server_error The model backend failed to answer. Please retry. Model yanıt üretmedi.
500 server_error An internal error occurred. Please retry. İstek hazırlanırken bir iç hata oluştu.
502 api_error The model backend failed to answer. Please retry. Model yanıt üretmedi. Shannon 3 ailesi ve host edilen açık ağırlıklı modeller.
503 api_error Could not verify your quota right now. Please retry. Bakiyeniz şu anda okunamadı.
503 api_error token counting is temporarily unavailable for this model Token sayma şu anda bu model için kullanılamıyor.
504 api_error upstream timed out Host edilen bir açık ağırlıklı model, akışsız bir isteğin zaman sınırından daha uzun sürdü.

Kontroller şu sırayla çalışır: API anahtarı, istek gövdesi, model kimliği, flood koruması, bakiye. Bu yüzden yanlış anahtarlı ve yanlış gövdeli bir istek 401 döndürür. Bir 4xx durumuyla reddedilen istek ücretlendirilmez.

Bakiye ve flood koruması

Her istek eşit şekilde sunulur: hız katmanları ve ayrı bir API kotası yoktur. Yine de iki şey 429 yanıtı verebilir; ikisi de rate_limit_error türündedir. Mesaj bunları birbirinden ayırır.

Bakiye

Bakiyeniz, 00:00 UTC'de sıfırlanan bugünün plan limiti ve ondan sonra satın alınan kredinizdir. Sohbet ve API aynı bakiyeden harcar.

Her istek önce çıktı sınırını ayırır: max_tokens veya /v1/responses üzerinde max_output_tokens; ikisini de göndermezseniz 4,096. Yanıt tamamlandığında ayrılan miktar, isteğin kullandığıyla değiştirilir. Miktar kalan bakiyeye sığmazsa istek, model başlamadan Quota exceeded döndürür.

Aynı anda çalışan istekler kendi miktarlarını ayrı ayrı ayırır. Bu yüzden yüksek max_tokens değerli çok sayıda paralel istek, her yanıt kısa olsa bile bakiyeyi bir an için tüketebilir. Daha düşük bir max_tokens daha az ayırır.

Flood koruması

Flood koruması hesap başına dakikada 120 isteğe izin verir. /v1/chat/completions, /v1/responses ve /v1/messages üzerindeki istekleri birlikte, anahtarı değil hesabı sayar. Dakika ilk isteğinizle başlar.

O dakika içindeki 121. istek Too many requests. Retry in <n>s. döndürür ve hiçbir şeye mal olmaz. Reddedilen istekler de sayılır; bu yüzden beklemeden tekrar gönderen bir istemci, dakika bitene kadar reddedilmeye devam eder. Mesajdaki <n> saniyeyi bekleyin.

Paralel gönderilen istekler paralel oldukları için reddedilmez. Sırada beklerler ve sırayla yanıtlanırlar.

GET /v1/models ve token sayma uç noktaları sayılmaz.

Limitler ve bakiye hakkında daha fazlası ve kendi bakiyenizi ve kullanımınızı nerede göreceğiniz: Limitler ve bakiye Keys & usage

Neler yeniden denenir

Bir isteği yalnızca aynı istek başarılı olabilecekse tekrar gönderin. OpenAI ve Anthropic SDK'ları 429 ve 5xx yanıtlarını zaten kendiliğinden iki kez yeniden dener; bunu değiştirmek için max_retries (JavaScript'te maxRetries) ayarlayın.

Hata Tekrar gönderilsin mi? Nasıl
400, 404, 405, 413, 415, 422 Hayır. Önce isteği düzeltin. Mesaj, yanlış olan alanı, modeli veya girdiyi belirtir.
401 Hayır. Geçerli bir anahtar kullanın. Anahtarı Keys & usage sayfasında oluşturun veya değiştirin.
429 Too many requests Evet, beklemeden sonra. Mesajdaki saniye kadar bekleyin, sonra aynı isteği gönderin.
429 Quota exceeded Olduğu gibi değil. max_tokens değerini düşürün, 00:00 UTC'deki günlük sıfırlamayı bekleyin veya kredi ekleyin.
429 Shannon Coder call quota reached Evet, sonraki pencerede. Pencereler 00:00 UTC'den itibaren her 4 saatte başlar. Başka bir model hemen yanıt verir.
429 … temporarily busy Evet. Birkaç saniye bekleyin, sonraki her denemede daha uzun bekleyin.
500, 502, 503 Evet. 1 saniye, sonra 2, 4 ve 8 saniye bekleyin. Birkaç denemeden sonra durun ve istek kimliğini bildirin.
504 Evet. stream değeri true olarak gönderin: zaman sınırı akışsız yanıtlar için geçerlidir.

Bu tabloyu izleyen bir yeniden deneme döngüsü:

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)

Bir akışın içindeki hatalar

Bir akışın durumu ilk baytından itibaren 200'dür. Bundan sonraki bir hata akışın içinde bir olay olarak gelir: /v1/chat/completions üzerinde error üyesi olan bir parça, /v1/messages üzerinde bir error olayı, /v1/responses üzerinde bir response.failed veya error olayı. Akışın kapanış olayları yine de gelir. Böyle bir yanıtı başarısız sayın ve isteği, bir 5xx durumunda olduğu gibi tekrar gönderin.

Modelin bağlam penceresinden uzun bir konuşma bu şekilde, invalid_request_error türü ve context_length_exceeded koduyla bildirilir. Tekrar göndermeden önce konuşmayı kısaltın.

Kesin çerçeveler streaming bölümünde açıklanır. Akış

İstek kimlikleri

Her yanıtta, hatalar dahil, bir x-request-id başlığı vardır. Bu, kendi x-request-id başlığınızda gönderdiğiniz değerdir veya hiçbir şey göndermediyseniz 12 onaltılık karakterdir. Kaydedin ve bir istek hakkında yardım isterken belirtin.