خطاها و کدهای وضعیت

همهٔ پاسخ‌های این API — موفق یا ناموفق — ساختار یکسانی دارند، بنابراین می‌توانید یک لایهٔ مدیریت خطای واحد بنویسید و همه‌جا از آن استفاده کنید.

ساختار پاسخ#

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": []
}

• return.status — کد وضعیت
• return.message — پیام فارسی قابل نمایش
• entries — داده‌های پاسخ. در پاسخ موفق یک شیء یا آرایه است و در همهٔ پاسخ‌های خطا آرایهٔ خالی [] برمی‌گردد.

چهار استثنا که قالب بالا را ندارند#

بیشتر سرویس‌ها دقیقاً همین قالب را برمی‌گردانند، ولی چهار مورد استثنا هستند و کلاینت شما باید آن‌ها را تحمل کند:

body = response.json()
result = body.get("return")
if result is None:
    # خطای غیرمنتظرهٔ سرور — پیام در کلید "message" است
    raise ServerError(body.get("message", "خطای ناشناخته"))

فهرست کدهای وضعیت#

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

موفق#

خطای درخواست#

خطای احراز هویت و دسترسی#

خطای اعتبار و سرور#

وضعیت پیامک (متفاوت با کد خطا)#

مقدار status که در پاسخ سرویس‌های استعلام برای هر پیامک برمی‌گردد، ربطی به کد وضعیت درخواست ندارد. این مقدار چرخهٔ عمر یک پیامک را نشان می‌دهد:

الگوی مدیریت خطا#

import requests
response = requests.post(url, json=payload, headers=headers)
body = response.json()          # بدنه را در هر حالتی بخوانید
result = body.get("return")
if result is None:              # خطای غیرمنتظرهٔ سرور (به هشدار بالا نگاه کنید)
    raise ServerError(body.get("message", "خطای ناشناخته"))
if result["status"] == 200:
    entries = body["entries"]
elif result["status"] == 418:
    raise OutOfCredit(result["message"])       # اعتبار کافی نیست
elif result["status"] in (401, 403, 416):
    raise AuthError(result["message"])         # کلید، حساب یا آی‌پی
elif result["status"] == 500:
    retry_later()                              # قابل تلاش مجدد
else:
    raise RequestError(result["status"], result["message"])