خطاها

دو شکل خطا، شش کد وضعیت، و روش برخورد با هرکدام.

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

دو شکل خطا

این‌که کدام بدنه را می‌گیرید به این بستگی دارد که کدام لایه درخواست را رد کرده است. خطاهای احراز هویت و مسیریابی را فریم‌ورک مدیریت می‌کند و فیلد detail برمی‌گرداند؛ بقیه را خود سرویس برمی‌گرداند و همان پوشش status و message موفقیت را دارند.

خطاهای فریم‌ورک — احراز هویت، مسیریابی، متد

{
  "detail": "Invalid API key"
}

خطاهای سرویس — اعتبارسنجی، نبود شیء، قواعد کسب‌وکار

{
  "status": "failed",
  "message": "Workspace not found"
}

اول message را بخوانید و اگر نبود به detail برگردید. همین یک خط، همهٔ خطاهای این API را پوشش می‌دهد.

کدهای وضعیت

شش کد، و دو کدی که نخواهید دید:

کد	معنی	چطور مدیریتش کنید
`400`	درخواست نادرست	اعتبارسنجی شکست خورده یا پارامتری الزامی جا افتاده است. پیام، نام فیلد را می‌گوید. بدون تغییر درخواست دوباره تلاش نکنید.
`402`	نیازمند پرداخت	اعتبار حسابی که این کلید به آن تعلق دارد تمام شده است. هر کاری که سراغ مدل می‌رود اعتبار خرج می‌کند — بارگذاری، گفت‌وگو، پردازش دوباره — پس تا شارژ نشود هیچ‌کدام موفق نمی‌شوند. تکرار همان درخواست فایده‌ای ندارد.
`403`	ممنوع	کلید API نیست یا نامعتبر است. توجه کنید که ۴۰۳ است، نه ۴۰۱ که بیشتر APIها برمی‌گردانند. پیش از آن‌که مشکل را به دسترسی نسبت بدهید، هدر را بررسی کنید.
`404`	پیدا نشد	شیء وجود ندارد، یا به اپ دیگری تعلق دارد. این API عمداً بین این دو تفاوتی نمی‌گذارد.
`405`	متد مجاز نیست	مسیر وجود دارد اما نه برای آن فعل. معمولاً نبودِ اسلش پایانی باعث شده POST پس از تغییر مسیر به GET تبدیل شود.
`500`	خطای سرور	چیزی سمت ما شکست خورده. یک‌بار با تأخیر فزاینده تلاش دوباره اشکالی ندارد؛ اگر ادامه داشت، زمان و مشخصات درخواست را به ما بگویید.

این API هنوز محدودیت نرخ ندارد، پس ۴۲۹ نخواهید دید — و نباید به نبودنش تکیه کنید. سقف خودتان را جلویش بگذارید، مخصوصاً اگر ترافیک کاربر نهایی را از آن رد می‌کنید.

هیچ چیزی ۴۰۹ برنمی‌گرداند. ساخت‌ها هرگز به‌عنوان تکراری رد نمی‌شوند.

400

{
  "status": "failed",
  "message": "{'external_user_id': [ErrorDetail(string='This field is required.', code='required')]}"
}

برخورد با خطاها

کلاینت کمینه‌ای که این را در همهٔ مسیرها درست انجام می‌دهد چنین شکلی دارد — توجه کنید که fetch روی 4xx هم resolve می‌شود، پس بررسی خود promise کافی نیست:

cURL

JavaScript

Python

# -f makes curl exit non-zero on a 4xx/5xx, and -sS keeps the message.
curl -fsS "https://api.daneshyar.info/api/v1/workspaces/" \
  -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \
  || echo "request failed"

دو شکل خطا

400

درخواست نادرست

اعتبارسنجی شکست خورده یا پارامتری الزامی جا افتاده است. پیام، نام فیلد را می‌گوید. بدون تغییر درخواست دوباره تلاش نکنید.

402

نیازمند پرداخت

اعتبار حسابی که این کلید به آن تعلق دارد تمام شده است. هر کاری که سراغ مدل می‌رود اعتبار خرج می‌کند — بارگذاری، گفت‌وگو، پردازش دوباره — پس تا شارژ نشود هیچ‌کدام موفق نمی‌شوند. تکرار همان درخواست فایده‌ای ندارد.

403

ممنوع

کلید API نیست یا نامعتبر است. توجه کنید که ۴۰۳ است، نه ۴۰۱ که بیشتر APIها برمی‌گردانند. پیش از آن‌که مشکل را به دسترسی نسبت بدهید، هدر را بررسی کنید.

404

پیدا نشد

شیء وجود ندارد، یا به اپ دیگری تعلق دارد. این API عمداً بین این دو تفاوتی نمی‌گذارد.

405

متد مجاز نیست

مسیر وجود دارد اما نه برای آن فعل. معمولاً نبودِ اسلش پایانی باعث شده POST پس از تغییر مسیر به GET تبدیل شود.

500

خطای سرور

چیزی سمت ما شکست خورده. یک‌بار با تأخیر فزاینده تلاش دوباره اشکالی ندارد؛ اگر ادامه داشت، زمان و مشخصات درخواست را به ما بگویید.

# -f makes curl exit non-zero on a 4xx/5xx, and -sS keeps the message. curl -fsS "https://api.daneshyar.info/api/v1/workspaces/" \ -H "X-API-Key: dk_live_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL" \ || echo "request failed"