Обработка на грешки и HTTP кодове
На тази страница
Актуализирано на 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!")
Обобщена таблица
Запазете тази мрежа под ръка: тя обобщава решението, което трябва да вземете за всеки код.
| Код | Изключение | Повторен опит? | Действие |
|---|---|---|---|
| 400 | BadRequestError | Не | Коригирайте заявката |
| 401 | AuthenticationError | Не | Проверете API ключа |
| 403 | PermissionDeniedError | Не | Проверете разрешенията |
| 404 | NotFoundError | Не | Проверете модела/крайната точка |
| 422 | UnprocessableEntityError | Не | Коригирайте формата |
| 429 | RateLimitError | Да | Експоненциално забавяне |
| 500 | InternalServerError | Да | Изчакайте и опитайте отново |
| 503 | InternalServerError | Да | Услугата е временно недостъпна |
Ключови изводи
- Класифицирайте грешките: повторяеми (429, 500, 503) срещу фатални (400, 401, 403)
- Използвайте експоненциално забавяне за повторяеми грешки
- Никога не повтаряйте опит при грешки в удостоверяването или невалидни заявки
- Регистрирайте всяка грешка с контекст (код, съобщение, времеви печат)
- SDK автоматично обработва 2 повторни опита – конфигурирайте
max_retries, ако е необходимо