0Pricing
AI Engineering Academy · Lekcja

Obsługa błędów i limity zapytań

Uczestnicy nauczą się obsługiwać typowe błędy API, w tym wyjątki związane z limitem zapytań, błędy uwierzytelniania i przekroczenia limitu czasu, korzystając z mechanizmów ponawiania oraz wykładniczego opóźnienia.

Obsługa błędów i limity zapytań to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

Dlaczego występują błędy API

Podczas wywołania API może pójść nie tak wiele rzeczy: przeciążenie, niski limit, przerwane połączenie sieciowe lub nieprawidłowe żądanie. Traktowanie wywołań jako niezawodnych gwarantuje kruchy kod — najpierw należy poznać typy błędów.

Przegląd typów błędów OpenAI

SDK zgłasza konkretne wyjątki, takie jak RateLimitError i AuthenticationError. Ponawiać warto tylko błędy przejściowe, takie jak przekroczenie limitu lub zerwanie połączenia sieciowego — pozostałe nie znikną samoistnie.

Przechwytywanie błędów za pomocą Try-Except

Każde wywołanie należy umieścić w try-except i przechwytywać konkretne wyjątki, a nie stosować pustego except. Dzięki temu można właściwie reagować na poszczególne awarie, zamiast ukrywać błędy. Kod pokazuje, jak to zrobić.

import openai

client = openai.OpenAI()

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello!'}]
    )
    print(response.choices[0].message.content)
except openai.AuthenticationError as e:
    print('Bad API key. Check OPENAI_API_KEY environment variable.')
    raise  # do not retry
except openai.RateLimitError as e:
    print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
    print('Network error:', e)
except openai.APIStatusError as e:
    print('Server error', e.status_code, e.message)

Zrozumienie limitów szybkości

OpenAI stosuje jednocześnie dwa limity szybkości: liczbę żądań na minutę (RPM) i liczbę tokenów na minutę (TPM). Jeden bardzo długi prompt może wyczerpać TPM w pojedynczym żądaniu. Oba przypadki zwracają kod 429.

Wykładnicze wycofywanie: właściwa strategia ponawiania

Przekroczono limit szybkości? Należy odczekać, a następnie ponowić próbę z użyciem wykładniczego wycofywania: 1 s, 2 s, 4 s, za każdym razem podwajając czas. Warto dodać niewielki jitter i maksymalną liczbę prób, aby uniknąć nieskończonej pętli. Zobacz kod.

import time
import random
import openai

client = openai.OpenAI()

def call_with_backoff(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model='gpt-4o-mini',
                messages=messages
            )
        except openai.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
            time.sleep(wait)
        except (openai.APIConnectionError, openai.APIStatusError):
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Korzystanie z biblioteki tenacity

Nie należy samodzielnie implementować mechanizmu ponawiania — biblioteka tenacity robi to przejrzyście. Wystarczy opatrzyć funkcję dekoratorem @retry, a biblioteka zajmie się wycofywaniem, jitterem i warunkami ponawiania.

from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai

client = openai.OpenAI()

@retry(
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
    return client.chat.completions.create(**kwargs)

response = completion_with_backoff(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)

Konfigurowanie limitu czasu

Zawieszone żądanie może zamrozić aplikację na zawsze, dlatego należy zawsze ustawiać limit czasu. SDK przyjmuje limit czasu w sekundach — dla klienta lub pojedynczego wywołania. Należy dobrać go do oczekiwanej długości odpowiedzi.

import openai

# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)

# Or override per request
try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
        timeout=60.0
    )
except openai.APITimeoutError:
    print('Request timed out. Try a shorter prompt or increase timeout.')

Obsługa błędów uwierzytelniania

AuthenticationError (401) oznacza, że klucz jest nieprawidłowy, wygasł lub został unieważniony — ponawianie prób nigdy nie pomoże. Należy zarejestrować błąd, wysłać alert i szybko zakończyć działanie zamiast zużywać limit prób.

import os
import openai

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY not set. Export it before running.'
    )

client = openai.OpenAI(api_key=api_key)

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello'}]
    )
except openai.AuthenticationError:
    # Do NOT retry - the key itself is invalid
    raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')

Limity wykorzystania a limity szybkości

Oba przypadki wyglądają jak RateLimitError, ale różnią się znaczeniem: limity szybkości są ograniczeniami liczby operacji na minutę i resetują się samoczynnie, natomiast limity wykorzystania określają maksymalne wydatki i wymagają dodatkowych środków.

Rejestrowanie błędów na potrzeby debugowania

Na produkcji należy rejestrować każdy błąd wraz z kontekstem: typem, modelem, parametrami, liczbą tokenów, czasem i identyfikatorem żądania. Ten identyfikator jest dokładnie tym, czego potrzebuje pomoc techniczna OpenAI. Zobacz kod.

import logging
import openai

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = openai.OpenAI()

def safe_completion(model, messages):
    try:
        response = client.chat.completions.create(
            model=model, messages=messages
        )
        return response
    except openai.RateLimitError as e:
        logger.warning(
            'Rate limit hit',
            extra={'model': model, 'error': str(e)}
        )
        raise
    except openai.APIStatusError as e:
        logger.error(
            'API server error',
            extra={
                'status_code': e.status_code,
                'request_id': e.request_id,
                'model': model
            }
        )
        raise

Obsługa błędów w aplikacjach produkcyjnych

Solidna strategia produkcyjna obejmuje szybkie kończenie działania w przypadku błędów nieodwracalnych, ponawianie prób dla błędów przejściowych z wycofywaniem oraz zapewnianie łagodnych mechanizmów zastępczych. Jeden błąd API nigdy nie powinien powodować awarii całego serwera.

Szybki test

Sprawdź swoją wiedzę na temat koncepcji inżynierii AI z tej lekcji.

Podsumowanie lekcji

Nauczyłeś się obsługiwać awarie: OpenAI zgłasza konkretne wyjątki, limity szybkości wymagają wycofywania z jitterem, a błędy uwierzytelniania powinny kończyć działanie bez ponawiania. Następnie: tworzenie skutecznych promptów.

Często zadawane pytania

Czy lekcja „Obsługa błędów i limity zapytań” jest bezpłatna?

Tak — pełny tekst „Obsługa błędów i limity zapytań” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Obsługa błędów i limity zapytań”?

Uczestnicy nauczą się obsługiwać typowe błędy API, w tym wyjątki związane z limitem zapytań, błędy uwierzytelniania i przekroczenia limitu czasu, korzystając z mechanizmów ponawiania oraz wykładnicze… Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?

Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Obsługa błędów i limity zapytań”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?

Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Konfigurowanie środowiska Python
  2. Endpoint Chat Completions
  3. Sterowanie zachowaniem modelu za pomocą parametrów
  4. Obsługa błędów i limity zapytań
← Powrót do AI Engineering Academy