خطاها

وقتی درخواستی شکست می‌خورد، HAPI v3 یک کد وضعیت واقعی HTTP و یک شیء خطای یکتا و قابل‌پیش‌بینی برمی‌گرداند. هیچ‌وقت خطایی پشت پاسخ 200 پنهان نمی‌شود.

شیء خطا#

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "slices is required.",
    "param": "slices",
    "doc_url": "https://api.simorghapi.com/docs/errors#validation_failed",
    "request_id": "req_z8iukwo8qwf488s01gthblxb"
  }
}

فیلد	توضیح
`type`	دستهٔ کلی خطا که می‌توانید منطق برنامه را بر اساس آن شاخه‌بندی کنید (پایین‌تر را ببینید).
`code`	کد دقیق و ماشین‌خوان برای همان مشکل مشخص.
`message`	توضیح قابل‌خواندن برای انسان. روی این رشته تطبیق (match) انجام ندهید.
`param`	وقتی خطا از یک فیلد مشخص باشد می‌آید و نام همان فیلد را می‌دهد.
`doc_url`	لینک مستندات مرتبط.
`request_id`	شناسهٔ این درخواست؛ آن را به پشتیبانی اعلام کنید.

انواع خطا#

نوع	HTTP	معنا
`authentication_error`	401	توکن ارسال نشده، نامعتبر یا منقضی است.
`permission_error`	403	توکن یکی از اسکوپ‌های لازم را ندارد.
`invalid_request_error`	400 / 422	درخواست ساختار نادرستی داشت یا اعتبارسنجی آن ناموفق بود.
`not_found_error`	404	هیچ منبعی پیدا نشد.
`conflict_error`	409	درخواست با وضعیت فعلی تعارض دارد.
`insufficient_balance`	402	کیف پول دفتر هزینهٔ رزرو را پوشش نمی‌دهد.
`rate_limit_error`	429	درخواست‌ها را بیش از حد سریع می‌فرستید.
`api_error`	5xx	مشکلی در سمت ما رخ داده است.

کدهای رایج#

کد	نوع	راه‌حل
`missing_authorization`	authentication	هدر `Authorization: Bearer` را اضافه کنید.
`invalid_token`	authentication	توکن ناشناخته است؛ توکن تازه بگیرید.
`expired_token`	authentication	توکن تازه بگیرید و دوباره تلاش کنید.
`invalid_client`	authentication	شناسه و کلید محرمانهٔ کلاینت را بررسی کنید.
`insufficient_scope`	permission	از توکنی استفاده کنید که اسکوپ ذکرشده در `detail` را دارد.
`validation_failed`	invalid_request	فیلدی را که در `param` آمده اصلاح کنید؛ `detail` همهٔ مشکلات را فهرست می‌کند.
`not_found`	not_found	شناسهٔ داخل مسیر را بررسی کنید.
`insufficient_balance`	insufficient_balance	کیف پول دفتر را شارژ کنید و دوباره تلاش کنید.
`rate_limited`	rate_limit	کمی صبر کنید و پس از وقفه‌ای کوتاه دوباره تلاش کنید.
`internal_error`	api	دوباره تلاش کنید؛ اگر ادامه داشت، با ذکر `request_id` به پشتیبانی (پنل → پشتیبانی) اطلاع دهید.

مدیریت خطاها#

رفتار برنامه را بر اساس type و حالت دقیق را بر اساس code تعیین کنید. خطاهای 429 و 5xx را با تأخیر نمایی (exponential backoff) دوباره امتحان کنید؛ اما خطاهای 4xx به‌جز 429 را کورکورانه تکرار نکنید، چون خود درخواست باید اصلاح شود. همیشه request_id را لاگ کنید.

جزئیات اعتبارسنجی. خطای 422 validation_failed یک شیء detail دارد که هر فیلد ردشده را به مشکلاتش نگاشت می‌کند؛ بنابراین می‌توانید همهٔ خطاها را یک‌جا به کاربر نشان دهید، نه یکی‌یکی.

ویرایش این صفحه در گیت‌هابمشکلی دیدید؟ از پنل ← پشتیبانی خبرمان کنید.