Премини към основното съдържание
Български— Изберете език
Меню

Обработка на грешки и HTTP кодове

Урок 12 от 22 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Обработка на грешки и HTTP кодове
  2. HTTP кодове на OpenAI API
  3. Комплексен обработчик на грешки
  4. Специфични грешки на Responses API
  5. Структурирано регистриране на грешки (Logging)
  6. Обобщена таблица
  7. Ключови изводи

Актуализирано на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите temperature и top_p се приемат само при усилие за разсъждение (reasoning effort) със стойност none, докато моделите GPT-5.6 разсъждават по подразбиране (medium). Следователно заявките, които задават тези параметри, трябва изрично да посочват reasoning={"effort": "none"} (Responses API) или reasoning_effort="none" (Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.

Изяснено на 3 ноември 2026 г. въз основа на страницата за Deprecated (спрени от употреба) на OpenAI: предишният пример за премахнат модел използваше gpt-4o, който остава достъпен до 14 януари 2027 г.; сега използва gpt-4-turbo, който беше спрян на 23 октомври 2026 г. (посочената замяна е gpt-5.6-sol). Източник: Deprecations.

Обработка на грешки и HTTP кодове

В производствена среда грешките са неизбежни. Мрежата прекъсва, API ключът изтича, колега внедрява невалиден параметър или самото API преживява три минутно прекъсване. Разбирането на HTTP кодовете, връщани от API, и правилната им обработка са от съществено значение за изграждането на надеждни приложения. Целият предизвикателство се свежда до един въпрос, който трябва да си зададете за всяко изключение: ще изчезне ли проблемът, ако опитам отново, или ще вляза в безкраен цикъл на проблем, който само човек може да реши?

HTTP кодове на OpenAI API

API връща стандартни HTTP кодове, за да покаже резултата от всяка заявка. Python SDK не Ви позволява да обработвате тези кодове ръчно; вместо това той превръща всеки от тях в типизирано изключение, което можете да прихванете поотделно. Това Ви позволява да пишете прецизни блокове except, вместо да използвате общ except Exception, който би замъглил същността на проблема.

from openai import OpenAI
from openai import (
    APIError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    APIConnectionError,
    InternalServerError,
    PermissionDeniedError,
    NotFoundError,
    UnprocessableEntityError,
)

client = OpenAI()

401 — AuthenticationError

Код 401 показва, че API ключът е невалиден или липсва. Обикновено срещате това при първото внедряване, когато променливата на средата не е била прехвърлена в контейнера. Повторният опит е безполезен: ключът ще бъде също толкова невалиден и след десет секунди.

try:
    # Невалиден или липсващ API ключ
    bad_client = OpenAI(api_key="sk-invalid")
    bad_client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except AuthenticationError as e:
    print(f"Code: {e.status_code}")  # 401
    print(f"Message: {e.message}")
    # Действие: проверете API ключа, регенерирайте го при необходимост

400 — BadRequestError

Код 400 Ви информира, че заявката е malformed (неправилно форматирана). Тук е предоставена стойност за температура от 5.0, когато максималната допустима стойност е 2.0. Съобщението за грешка почти винаги посочва дефектния параметър, което прави това най-бързата за поправяне грешка – стига да я регистрирате правилно, вместо да я поглъщате тихо.

try:
    # Невалидни параметри
    client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature изисква effort none
        input="Test",
        temperature=5.0  # Невалидна стойност (макс. 2.0)
    )
except BadRequestError as e:
    print(f"Code: {e.status_code}")  # 400
    print(f"Message: {e.message}")
    # Действие: коригирайте параметрите на заявката

429 — RateLimitError

Код 429 показва, че изпращате твърде много заявки или сте надвишили квотата си. За разлика от предходните две, тази грешка е временна по природа: броячът се нулира. Това е класическият случай за повторен опит, но такъв, който изчаква – и изчаква все по-дълго с всеки следващ опит.

try:
    # Твърде много заявки или надвишена квота
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except RateLimitError as e:
    print(f"Code: {e.status_code}")  # 429
    print(f"Message: {e.message}")
    # Действие: изчакайте и опитайте отново с експоненциално забавяне

500/503 — InternalServerError

Грешките 500 и 503 идват от OpenAI, а не от Вас. Вашата заявка е валидна; инфраструктурата просто не е успяла да я обработи. Опитайте отново след известно забавяне: в огромното мнозинство от случаите вторият или третият опит успява.

try:
    client.responses.create(
        model="gpt-5.6-terra",
        input="Test"
    )
except InternalServerError as e:
    print(f"Code: {e.status_code}")  # 500 или 503
    print(f"Message: {e.message}")
    # Действие: опитайте отново след забавяне; грешката е от страна на OpenAI

Комплексен обработчик на грешки

Нека обединим тези поведения в една единствена функция. Логиката е триаж: фаталните грешки се превръщат в RuntimeError и се генерират незабавно, преходните грешки задействат изчакване, което се удвоява при всеки завой, а ако бюджетът за опити се изчерпи, извикването се проваля чисто, вместо да връща празна стойност, която caller-ът може да тълкува погрешно.

from openai import OpenAI, APIError, AuthenticationError, RateLimitError
from openai import BadRequestError, APIConnectionError, InternalServerError
import time

client = OpenAI()

def robust_api_call(prompt: str, model: str = "gpt-5.6-terra",
                    max_retries: int = 3) -> str:
    """API извикване с комплексна обработка на грешки."""

    for attempt in range(max_retries):
        try:
            response = client.responses.create(
                model=model,
                input=prompt
            )
            return response.output_text

        except AuthenticationError:
            # Не повтаряйте – ключът е невалиден
            raise RuntimeError("Невалиден API ключ. Проверете OPENAI_API_KEY.")

        except BadRequestError as e:
            # Не повтаряйте – заявката е неправилно форматирана
            raise RuntimeError(f"Невалидна заявка: {e.message}")

        except RateLimitError:
            # Повторен опит с експоненциално забавяне
            delay = 2 ** attempt
            print(f"Достигнат лимит на заявките. Изчакване {delay}s...")
            time.sleep(delay)

        except InternalServerError:
            # Повторен опит – грешка от страна на сървъра
            delay = 2 ** attempt
            print(f"Сървърна грешка. Опит {attempt + 1}/{max_retries}...")
            time.sleep(delay)

        except APIConnectionError:
            # Повторен опит – мрежов проблем
            delay = 2 ** attempt
            print(f"Грешка във връзката. Опит {attempt + 1}/{max_retries}...")
            time.sleep(delay)

    raise RuntimeError(f"Неуспех след {max_retries} опита")

# Употреба
try:
    result = robust_api_call("Hello!")
    print(result)
except RuntimeError as e:
    print(f"Фатална грешка: {e}")

Специфични грешки на Responses API

Две ситуации заслужават отделно третиране, защото се появяват под общ код, но изискват много специфично поправяне.

Контекстът е твърде дълъг

Подкана (prompt), която надвишава прозореца на контекста, връща код 400, точно както печатна грешка в параметър. За да разграничите двете, проверете съобщението: наличието на context_length_exceeded Ви насочва към съкращаване на текста или превключване към модел с по-голям прозорец на контекста, вместо да преглеждате параметрите си.

try:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="x " * 300000  # Надвишава прозореца на контекста
    )
except BadRequestError as e:
    if "context_length_exceeded" in str(e.message):
        print("Подканата е твърде дълга за този модел.")
        print("Решения: съкратете текста или преминете към модел")
        print("с по-голям прозорец на контекста.")

Моделът е недостъпен

Идентификаторите на моделите не са вечни. Внедряване, което все още се позовава на пенсиониран модел, се проваля с код 404, причинявайки срив на цялото приложение, въпреки че е работило предния ден. Обработете този случай изрично: това е автоматично напомняне да актуализирате конфигурацията си.

try:
    response = client.responses.create(
        model="gpt-4-turbo",  # спрян от API на 23 октомври 2026 г.
        input="Test"
    )
except NotFoundError as e:
    print(f"Моделът не е намерен: {e.message}")
    print("Използвайте gpt-5.6-sol, заменителя, посочен от OpenAI, или по-нов модел.")

Структурирано регистриране на грешки (Logging)

Грешка, която не е регистрирана, е грешка, за която ще разберете чрез билет от клиент. Регистрирането в JSON формат, вместо като свободен текст, променя всичко, когато трябва да агрегирате данни: можете да броите 429 грешки на час, да филтрирате по response_id или да проследявате отклонения в потреблението, което е невъзможно с ръчно написани редове в логовете.

import logging
import json
from datetime import datetime

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("openai_client")

def call_with_log(prompt: str) -> str:
    """API извикване със структурирано регистриране."""
    request_id = None

    try:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt
        )

        logger.info(json.dumps({
            "event": "api_success",
            "model": response.model,
            "tokens": response.usage.total_tokens,
            "response_id": response.id,
            "timestamp": datetime.now().isoformat()
        }))

        return response.output_text

    except APIError as e:
        logger.error(json.dumps({
            "event": "api_error",
            "status_code": e.status_code,
            "message": e.message,
            "timestamp": datetime.now().isoformat()
        }))
        raise

result = call_with_log("Hello!")

Обобщена таблица

Запазете тази мрежа под ръка: тя обобщава решението, което трябва да вземете за всеки код.

КодИзключениеПовторен опит?Действие
400BadRequestErrorНеКоригирайте заявката
401AuthenticationErrorНеПроверете API ключа
403PermissionDeniedErrorНеПроверете разрешенията
404NotFoundErrorНеПроверете модела/крайната точка
422UnprocessableEntityErrorНеКоригирайте формата
429RateLimitErrorДаЕкспоненциално забавяне
500InternalServerErrorДаИзчакайте и опитайте отново
503InternalServerErrorДаУслугата е временно недостъпна

Ключови изводи

  • Класифицирайте грешките: повторяеми (429, 500, 503) срещу фатални (400, 401, 403)
  • Използвайте експоненциално забавяне за повторяеми грешки
  • Никога не повтаряйте опит при грешки в удостоверяването или невалидни заявки
  • Регистрирайте всяка грешка с контекст (код, съобщение, времеви печат)
  • SDK автоматично обработва 2 повторни опита – конфигурирайте max_retries, ако е необходимо