کد خطای ارائه‌دهنده نباید مستقیم قرارداد برنامه شما شود. ممکن است یک سرویس برای نبود اعتبار و دیگری برای محدودیت نرخ کدهای متفاوت بدهد. لایه واسط باید معنای خطا را به کد دامنه پایدار نگاشت کند تا مشتری نرم‌افزاری تصمیم درست بگیرد. این راهنما درباره قرارداد ماشین‌خوان است، نه فقط متن خطای فرم.
کد دامنه و وضعیت HTTP را جدا تعریف کنید
فهرست کوتاهی مانند INPUT_INVALID،AI_RATE_LIMITED و AI_UNAVAILABLE بسازید. برای هرکدام بگویید تکرار خودکار مجاز است یا نه و چه داده تکمیلی لازم دارد. محدودیت نرخ با نداشتن اعتبار حساب یکی نیست؛ دومی ممکن است به تصمیم مدیر حساب نیاز داشته باشد، نه retry بی‌پایان کاربر.
RFC 9457 برای خطای قابل پردازش قالبی با نوع، عنوان و وضعیت معرفی می‌کند. در نمونه زیر از همان ساختار استفاده شده و code و correlation_id افزونه اختصاصی نمونه‌اند. قرارداد باید این افزونه‌ها را مستند کند؛ استاندارد بودن قالب، معنی کد سفارشی شما را به کتابخانه‌ها آموزش نمی‌دهد.
نمونه پاسخ محدودیت نرخ
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 30
{
"type": "urn:example:problem:ai-rate-limited",
"title": "ظرفیت موقت درخواست پر است",
"status": 429,
"code": "AI_RATE_LIMITED",
"retryable": true,
"correlation_id": "demo-corr-01"
}مقدار۳۰ صرفاً زمان انتظار ساختگی است. اگر سرویس زمان معتبری داده، واسط باید آن را با بودجه و سیاست داخلی بررسی کند؛ اگر زمان معلوم نیست، عدد دلخواه نسازد. Retry-After می‌تواند طبق قرارداد HTTP شکل زمانی متفاوت داشته باشد، پس parser مقصد باید شکل‌های پشتیبانی‌شده را روشن کند. retryable=true نیز به معنی اجازه اجرای دوباره هر اقدام نوشتنی نیست؛ کلید اقدام و وضعیت اثر باید جدا کنترل شوند.
| ورودی ارائه‌دهنده ساختگی | کد دامنه | HTTP نمونه | تکرار |
|---|---|---|---|
| محدودیت نرخ | AI_RATE_LIMITED | 429 | با زمان و سقف معتبر |
| اعتبار حساب تمام | AI_ACCOUNT_ACTION_REQUIRED | 503 | خودکار نه |
| ورودی نامعتبر | INPUT_INVALID | 400 | پس از اصلاح ورودی |
تغییر ارائه‌دهنده نباید قرارداد را بشکند
پاسخ‌های خطای ساختگی دو ارائه‌دهنده را به adapter بدهید و انتظار داشته باشید خروجی دامنه یکسان بماند. فیلد ناشناس باید به حالت خطای کنترل‌شده برود، نه موفقیت پیش‌فرض. وضعیت داخل JSON با status خط پاسخ هماهنگ باشد. شناسه پیگیری یک مقدار بی‌اطلاعات و مجاز است و نباید ایمیل یا کلید حساب را در خود داشته باشد.
پاسخ خام سرویس در خروجی عمومی قرار نمی‌گیرد؛ فقط شاهد محدود در مسیر مجاز ثبت می‌شود. این قرارداد سیاست پیشنهادی یک برنامه نمونه است و نگاشت کد همه سرویس‌ها محسوب نمی‌شود. برای SDK واقعی، شکل خطا و نسخه آن را بخوانید و بعد مجموعه آزمون نگاشت را به‌روز کنید.
کاربرگ همراه و منبع
دریافت CSV اختصاصی این راهنما؛ تمام رکوردها و شناسه‌های کاربرگ ساختگی‌اند. مقادیر نمونه را به داده یا نتیجه واقعی مشتری تعبیر نکنید.
RFC 9457: قالب خطای قابل پردازش HTTP؛ MDN: 429 و Retry-After. منابع در ۱ نوامبر ۲۰۲۶ خوانده شدند؛ مثال و الگوی اجرایی بالا پیشنهاد آموزشی تحریریه است، نه تأیید قابلیت محصول.
اگر این مسئله در مسیر پاسخ‌گویی مشتری شما وجود دارد، آموزش‌های اپرا را ببینید و همین کاربرگ را برای بررسی دامنه و محدودیت در دمو آماده کنید.