Paghawak ng Error

Nagtataas ang mga SDK ng error object na may dalang status code at mga field ng body. Pinangangalanan ng request na ito ang model na hindi umiiral:

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.shannon-ai.com/v1",
});

try {
  await client.chat.completions.create({
    model: "no-such-model",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (!(error instanceof OpenAI.APIError)) throw error;
  console.log(error.status);         // 400
  console.log(error.type);           // invalid_request_error
  console.log(error.error.message);  // unknown model: no-such-model
}

curl -i https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "no-such-model",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Nagbabalik ito ng status na 400 at ng body na ito:

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

Error body

Dalawa ang body. Sumasagot ang /v1/messages sa Anthropic format; ang bawat ibang endpoint ay sumasagot sa OpenAI format. Sa pareho, nasa error.type at error.message ang mga detalye, kaya iisang reader ang magagamit sa lahat ng endpoint.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Mga error type

Mga status code

Tumatakbo ang mga pagsusuri sa pagkakasunod na ito: API key, request body, model id, flood protection, balance. Kaya ang request na may maling key at maling body ay nagbabalik ng 401. Ang request na tinanggihan ng 4xx na status ay hindi sinisingil.

Balance at flood protection

Pantay ang pagsilbi sa bawat request: walang rate tier at walang hiwalay na API quota. Dalawang bagay pa rin ang maaaring sumagot ng 429, parehong may type na rate_limit_error. Ang mensahe ang nagpapakilala sa kanila.

Balance

Ang iyong balance ay ang plan allowance ngayong araw, na nagre-reset sa 00:00 UTC, at pagkatapos nito ang biniling credit. Parehong balance ang kinukuhanan ng chat at ng API.

Unang itinatabi ng bawat request ang output limit nito: max_tokens, o max_output_tokens sa /v1/responses, 4,096 kapag wala kang ipinadala. Kapag kumpleto na ang reply, pinapalitan ang itinabing halaga ng aktuwal na nagamit ng request. Kung hindi kasya ang halaga sa natitirang balance, nagbabalik ang request ng Quota exceeded bago magsimula ang model.

Ang mga request na sabay na tumatakbo ay nagtatabi ng kani-kanilang halaga. Kaya ang maraming parallel na request na may mataas na max_tokens ay maaaring pansamantalang makaubos ng balance, kahit maikli ang bawat reply. Mas kaunti ang itinatabi ng mas mababang max_tokens.

Flood protection

Pinapayagan ng flood protection ang 120 request kada minuto kada account. Binibilang nito ang account, hindi ang key, sa /v1/chat/completions, /v1/responses at /v1/messages nang magkakasama. Nagsisimula ang minuto sa una mong request.

Ang request bilang 121 sa loob ng minutong iyon ay nagbabalik ng Too many requests. Retry in <n>s. at walang gastos. Binibilang din ang mga tinanggihang request, kaya ang client na nagpapadala muli nang hindi naghihintay ay mananatiling tinatanggihan hanggang matapos ang minuto. Hintayin ang <n> segundo mula sa mensahe.

Hindi tinatanggihan ang mga request na sabay-sabay na ipinadala dahil lang sa pagiging sabay-sabay. Naghihintay sila sa pila at sinasagot nang sunud-sunod.

Hindi binibilang ang GET /v1/models at ang mga token counting endpoint.

Higit pa tungkol sa mga limitasyon at balance, at kung saan makikita ang sarili mong balance at usage: Mga limitasyon at balance Keys & usage

Ano ang dapat i-retry

Ipadala muli ang request kung may pag-asang magtagumpay ang parehong request. Kusa nang nagre-retry nang dalawang beses ang mga OpenAI at Anthropic SDK sa mga reply na 429 at 5xx; i-set ang max_retries (maxRetries sa JavaScript) para baguhin iyon.

Isang retry loop na sumusunod sa talahanayang ito:

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)

import OpenAI from "openai";

// maxRetries: 0 — this loop does the retrying, the SDK does not add its own.
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1", maxRetries: 0 });

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function createWithRetry(request, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    try {
      return await client.chat.completions.create(request);
    } catch (error) {
      const text = String(error.message);
      const flood = text.match(/Retry in (\d+)s/);
      if (error.status === 429 && flood) {
        await sleep(Number(flood[1]));            // flood protection: wait out the minute
      } else if (error.status === 429 && text.includes("temporarily busy")) {
        await sleep(2 ** attempt);
      } else if (error.status >= 500 || error instanceof OpenAI.APIConnectionError) {
        await sleep(2 ** attempt);                // 1, 2, 4, 8 seconds
      } else {
        throw error;                              // wrong request, wrong key or balance
      }
    }
  }
  throw new Error("the request failed after all attempts");
}

const response = await createWithRetry({
  model: "shannon-3",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

Mga error sa loob ng stream

May status na 200 ang stream mula sa unang byte nito. Ang pagkabigo pagkatapos noon ay dumarating bilang event sa loob ng stream: isang chunk na may miyembrong error sa /v1/chat/completions, isang error event sa /v1/messages, isang response.failed o error event sa /v1/responses. Sumusunod pa rin ang mga pangwakas na event ng stream. Ituring na nabigo ang ganoong reply at ipadala muli ang request, tulad ng sa 5xx na status.

Ang conversation na mas mahaba kaysa sa context window ng model ay iniuulat sa ganitong paraan, na may type na invalid_request_error at code na context_length_exceeded. Paikliin ang conversation bago ito ipadala muli.

Inilalarawan ang eksaktong mga frame kasama ng streaming. Pag‑stream

Mga request id

May header na x-request-id ang bawat reply, kasama ang mga error. Ito ang value na ipinadala mo sa sarili mong x-request-id header, o 12 hexadecimal na character kapag wala kang ipinadala. I-log ito, at banggitin ito kapag humihingi ka ng tulong sa isang request.