خطای ۴۰۰، ۴۰۲ و ۴۲۹ مدل زبانی: چه زمانی درخواست را تکرار کنیم؟

هر خطای API مدل زبانی با تکرار درخواست حل نمی‌شود. با یک سیاست کوچک در پایتون، خطای ورودی و اعتبار حساب را از محدودیت موقت نرخ جدا کنید.

برای سارا، توسعه‌دهنده بک‌اند یک دستیار پشتیبانی، سیاست امن این است: ۴۰۰ را بدون تغییر ورودی تکرار نکن؛ ۴۰۲ را به مسیر بررسی پرداخت بفرست؛ و ۴۲۹ را فقط وقتی محدودیت موقت نرخ است، با انتظار و سقف تلاش تکرار کن. نتیجه عملی، جلوگیری از حلقه‌ای است که هم صف پاسخ‌ها را طولانی می‌کند و هم درخواست‌های بی‌فایده می‌فرستد.

اول علت را طبقه‌بندی کنید، نه فقط شماره خطا را

۴۰۰ معمولاً یعنی درخواست از نظر سرویس نامعتبر است: مثلاً پارامتر ناسازگار، ساختار پیام نادرست یا ورودی بزرگ‌تر از حد مجاز. همان درخواست با همان تنظیمات، صرفاً با گذشت زمان درست نمی‌شود. شناسه درخواست، نام مدل و کد ساخت‌یافته خطا را ثبت کنید و اصلاح را در سازنده درخواست انجام دهید؛ متن کامل پیام کاربر را برای عیب‌یابی بی‌محابا وارد لاگ نکنید.

۴۰۲ در استاندارد HTTP برای استفاده آینده رزرو شده است؛ بنابراین قرارداد عمومی و یکسانی برای پرداخت در APIهای مدل زبانی ندارد. اگر ارائه‌دهنده شما آن را برای اعتبار ناکافی یا مشکل پرداخت تعریف کرده، تکرار خودکار را متوقف و مسئول حساب را مطلع کنید. در غیر این صورت، آن را خطای غیرقابل‌تکرارِ نیازمند بررسی بدانید، نه مدرک قطعی تمام‌شدن اعتبار.

۴۲۹ حساس‌ترین شاخه است. در مستندات OpenAI، هم عبور از نرخ مجاز و هم تمام‌شدن سهمیه می‌توانند با این وضعیت گزارش شوند. پس علاوه بر وضعیت HTTP، کد ساخت‌یافته بدنه را بخوانید: insufficient_quota را به مسیر اعتبار و سهمیه بفرستید، نه صف تکرار. برای محدودیت موقت، Retry-After را اگر وجود دارد رعایت کنید؛ نبودن این هدر به معنی مجازبودن تکرار فوری نیست.

یک سیاست قابل‌آزمایش با پایتون

کد زیر هسته تصمیم‌گیری را از شبکه جدا می‌کند. ورودی آن وضعیت HTTP، کد خطای بدنه، هدرها و تعداد تکرارهای انجام‌شده است. خروجی یک اقدام و زمان انتظار است؛ در برنامه واقعی فقط برای retry منتظر بمانید و درخواست را دوباره بفرستید. این مثال عمداً درخواست شبکه ندارد تا بدون کلید API و هزینه اجرا شود.

```python
import math
import random


def decide(status, error_code='', headers=None, retries_done=0,
rng=random.uniform):
headers = {k.lower(): v for k, v in (headers or {}).items()}
if status == 400:
return 'fix_request', None
if status == 402:
return 'check_billing_contract', None
if status != 429:
return 'outside_policy', None
if error_code == 'insufficient_quota':
return 'check_quota', None
if retries_done >= 3:
return 'retry_exhausted', None

raw = headers.get('retry-after')
if raw is not None:
try:
wait = float(raw)
except (ValueError, TypeError):
return 'inspect_retry_after', None
if not math.isfinite(wait) or wait < 0:
return 'inspect_retry_after', None
# Do not shorten a server-requested delay to fit our budget.
if wait > 30:
return 'defer_to_queue', None
return 'retry', wait

# Exponential backoff with jitter; seconds.
ceiling = min(30.0, 2.0 ** (retries_done + 1))
return 'retry', rng(ceiling / 2, ceiling)


cases = [
('bad_input', 400, '', {}, 0),
('payment', 402, '', {}, 0),
('quota', 429, 'insufficient_quota', {}, 0),
('rate_header', 429, 'rate_limit_exceeded', {'Retry-After': '2'}, 0),
('rate_backoff', 429, 'rate_limit_exceeded', {}, 1),
('long_wait', 429, '', {'Retry-After': '120'}, 0),
('exhausted', 429, '', {}, 3),
]

for name, status, code, headers, count in cases:
# Fixed midpoint for deterministic test output only.
action, wait = decide(status, code, headers, count,
rng=lambda low, high: (low + high) / 2)
print(f'{name}: {action}, wait={wait}')
```

فایل را با نام retry_policy.py ذخیره و با دستور زیر اجرا کنید. فهرست cases ورودی آزمایش است: از درخواست خراب تا انتظار ۱۲۰ثانیه‌ای. برای خروجی ثابت، مولد تصادفی در آزمایش با نقطه میانی بازه جایگزین شده است؛ در محیط واقعی این جایگزینی را انجام ندهید تا کلاینت‌ها هم‌زمان دوباره هجوم نبرند.

```bash
python3 retry_policy.py
```

خروجی مورد انتظار چنین است. سقف سه تکرار یعنی حداکثر چهار ارسال با احتساب درخواست اولیه؛ پس از هر ارسال مجدد، شمارنده retries_done باید افزایش یابد. مرز ۳۰ ثانیه صرفاً بودجه انتخابی این نمونه برای یک درخواست تعاملی است، نه محدودیت سرویس.

```other
bad_input: fix_request, wait=None
payment: check_billing_contract, wait=None
quota: check_quota, wait=None
rate_header: retry, wait=2.0
rate_backoff: retry, wait=3.0
long_wait: defer_to_queue, wait=None
exhausted: retry_exhausted, wait=None
```

کجا این سیاست شکست می‌خورد؟

اولین دام، تکرار در دو لایه است. SDK پایتون OpenAI به‌صورت پیش‌فرض بعضی خطاها، از جمله ۴۲۹، را دو بار تکرار می‌کند. اگر این سیاست مالک تکرار باشد، کلاینت را با OpenAI(max_retries=0) بسازید. در غیر این صورت، شمارش تلاش و بودجه تأخیر شما با ارسال‌های واقعی یکسان نیست. انتخاب جایگزین، سپردن تکرار به SDK است؛ ساده‌تر است، اما تصمیم‌های مخصوص سهمیه و صف را همچنان باید در لایه کاربرد مدیریت کنید.

دومین دام، اشتباه‌گرفتن کنترل یک درخواست با کنترل کل سامانه است. وقتی ده‌ها worker به یک سهمیه مشترک وصل‌اند، backoff محلی تضمین نمی‌کند نرخ مجموع پایین بیاید. محدودکردن هم‌زمانی یا صف مشترک، توان عملیاتی لحظه‌ای را کاهش می‌دهد اما از موج خطا جلوگیری می‌کند. برای کار تعاملی، انتظار طولانی را به پیام «فعلاً در دسترس نیست» تبدیل کنید؛ برای کار پس‌زمینه، آن را با زمان اجرای بعدی در صف بگذارید، نه اینکه worker را طولانی‌مدت معطل نگه دارید.

این روش برای بازیابی استریم نیمه‌کاره یا تکرار عملیات ابزار مناسب نیست. اگر مدل قبلاً بخشی از متن را فرستاده یا ابزار جانبی عملی انجام داده، اجرای دوباره ممکن است خروجی یا اثر جانبی تکراری بسازد؛ آن مسیر به ثبت وضعیت و طراحی جلوگیری از اجرای تکراری نیاز دارد. همچنین در محیط عملیاتی، تعداد تلاش کافی نیست: یک مهلت کل برای درخواست بگذارید و اگر انتظار بعدی از آن عبور می‌کند، تکرار را کنار بگذارید.

منابع

OpenAI API — Error codes
https://platform.openai.com/docs/guides/error-codes

OpenAI API — Rate limits
https://platform.openai.com/docs/guides/rate-limits

OpenAI Python SDK — Retries
https://github.com/openai/openai-python#retries

RFC 9110 — HTTP Semantics
https://www.rfc-editor.org/rfc/rfc9110.html

RFC 6585 — Additional HTTP Status Codes
https://www.rfc-editor.org/rfc/rfc6585.html

No comments yet