قالب خطاها
وقتی endpointهای سایت درخواست پاتریس یار را نمیپذیرند، باید کد HTTP مناسب و یک بدنهی JSON با code و message برگردانند. پاتریس یار بر اساس همین دو مقدار پیام خطا را به کاربر فروشگاه نشان میدهد.
پاسخ خطا چه شکلی باشد؟
401 Unauthorized
{
"code": "payava_patris_unauthorized",
"message": "Invalid API key"
}
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
code | string | بله | کد کوتاه و انگلیسی خطا. |
message | string | بله | توضیح خطا. اگر فارسی بنویسید، کاربر فروشگاه هم آن را میفهمد. |
پاتریس یار قالب ProblemDetails (title و detail) را هم میخواند. اگر بدنه JSON نباشد، تا ۳۰۰ کاراکتر اول آن به عنوان پیام نشان داده میشود.
پاتریس یار برای هر خطا چه میگوید؟
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 یا 403 | هر code | — | پاتریس یار میگوید کلید API پذیرفته نشد و باید همان کلید سایت را وارد کرد. |
403 | payava_patris_license | — | پاتریس یار میگوید «سایت اتصال را نپذیرفت» و متن message را کنارش نشان میدهد. برای ردِ آگاهانه با پیام دلخواه از این کد استفاده کنید. |
404 | هر code | — | پاتریس یار میگوید مسیر اتصال روی سایت پیدا نشد. «آدرس API» در پاتریس یار و مسیرهای وبسرور را بررسی کنید. |
429 | هر code | — | پاتریس یار میگوید سایت فعلاً درخواست بیشتری نمیپذیرد و دور بعد دوباره تلاش میکند. |
| سایر کدها | هر code | — | پاتریس یار کد HTTP و code (یا message) را نشان میدهد. |
استثنا: 404 در GET /patris-yar/orders/:id خطا حساب نمیشود و فقط یعنی سفارش وجود ندارد.
بعد از خطا چه اتفاقی میافتد؟
- پاتریس یار خطا را در وضعیت همان اتصال نشان میدهد و در log خود ثبت میکند.
- دور بعد همگامسازی، همان کار دوباره انجام میشود. سفارشها، اعلام وضعیتها و ردیفهای کالا تا پاسخ موفق، «انجامشده» حساب نمیشوند.
- خطای دریافت سفارش جلوی ارسال قیمت و موجودی را نمیگیرد و برعکس.
نکتهها
پیام خطای داخلی را برنگردانید
stack trace، رشتهی اتصال پایگاه داده یا مسیر فایلهای سرور را در message نگذارید. این پیام در برنامهی رایانهی فروشگاه نمایش داده میشود.
- همهی پاسخها، چه موفق و چه خطا،
Content-Type: application/json; charset=utf-8داشته باشند. - صفحهی HTML خطا (مثلاً صفحهی ۵۰۰ وبسرور یا چالش فایروال) پیام نامفهوم به کاربر نشان میدهد.