پرش به محتوای مستندات
مستندات توسعه‌دهندگانGift City API v1API Key
کدهای خطا
Errors

خطاها و روش بازیابی

API علاوه بر status استاندارد HTTP، یک code داخلی و پیام قابل‌خواندن برمی‌گرداند. منطق برنامه را بر اساس HTTP status و code پیاده کنید، نه متن پیام.

ساختار پاسخ خطا

فیلد meta اختیاری است و در بعضی خطاها اطلاعات تکمیلی مانند موجودی فعلی، مبلغ لازم یا زمان retry را دارد.

نمونه پاسخ خطاjson
{
  "status": "error",
  "code": 1004,
  "message": "موجودی کیف پول کافی نیست",
  "meta": {
    "currentBalance": 120000,
    "requiredAmount": 490000
  }
}

کدهای قابل مدیریت

HTTP 400code 1004
موجودی کیف پول کافی نیست

موجودی و مبلغ سفارش را بررسی کنید.

HTTP 400code 1006
محصول یا پراپرتی موجود نیست

کاتالوگ و وضعیت موجودی را دوباره بخوانید.

HTTP 400code 1007
شناسه یا پارامتر نامعتبر است

نوع داده و مقدار پارامتر را اصلاح کنید.

HTTP 400code 1008
دسته‌بندی نامعتبر است

شناسه را از endpoint دسته‌بندی‌ها بگیرید.

HTTP 401code 1001
API Key ارسال نشده یا معتبر نیست

هدر X-API-KEY و فعال بودن کلید را بررسی کنید.

HTTP 403code 1003
IP درخواست مجاز نیست

IP خروجی سرور را به whitelist اضافه کنید.

HTTP 404code 1005 / 404
منبع مورد نظر پیدا نشد

شناسه و مالکیت منبع را بررسی کنید.

HTTP 405code 405
متد HTTP مجاز نیست

از متد ثبت‌شده در مرجع endpoint استفاده کنید.

HTTP 429code 1002
تعداد درخواست بیش از حد مجاز است

طبق Retry-After با تأخیر دوباره تلاش کنید.

HTTP 500code 500
خطای داخلی سرویس

با backoff تلاش کنید و در تکرار خطا گزارش دهید.

Retry و backoff

فقط خطاهای موقت مانند 429 و 5xx را دوباره امتحان کنید. خطاهای اعتبارسنجی و احراز هویت تا زمان اصلاح ورودی نباید retry شوند.

نمونه retry کنترل‌شدهjavascript
async function requestWithRetry(url, options, attempt = 0) {
  const response = await fetch(url, options);

  if (response.status === 429 && attempt < 3) {
    const retryAfter = Number(response.headers.get("Retry-After") || 2);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return requestWithRetry(url, options, attempt + 1);
  }

  if (response.status >= 500 && attempt < 3) {
    await new Promise(resolve => setTimeout(resolve, 2 ** attempt * 1000));
    return requestWithRetry(url, options, attempt + 1);
  }

  return response;
}