واجهة API للشركاء (B2B)

Errors & rate limits

Partner API error codes, per-key rate limits with X-RateLimit headers, and how to retry.

On this page

Error format
Error codes
Rate limits
Retrying

Error format#

تأتي أجسام الأخطاء بالشكل { statusCode, code, message }. الحقل message نص إنجليزي مقروء وقد يتغير، لذا اعتمد دائمًا على code في منطقك.

json

// Success
{ "success": true, "data": ..., "total": 128, "page": 1, "limit": 20 }

// Error
{ "statusCode": 401, "code": "INVALID_API_KEY", "message": "The API key is invalid." }

ملاحظة

تستخدم أخطاء التحقق من الاستعلام (400) التنسيق القياسي { statusCode: 400, message: [...], error: "Bad Request" } دون رمز.

Error codes#

HTTP	code	المعنى والحل
401	API_KEY_REQUIRED	لم يتم إرسال مفتاح — أضف الترويسة X-API-Key
401	INVALID_API_KEY	مفتاح غير صالح الصيغة أو غير معروف — تأكد من أن النسخ لم يكن مبتورًا وأنه ليس مفتاح API العامة
401	KEY_REVOKED	مفتاح مُبطَل — أنشئ مفتاحًا جديدًا
401	KEY_EXPIRED	مفتاح منتهي الصلاحية (بما في ذلك المفتاح القديم بعد انتهاء فترة السماح للتدوير) — استخدم المفتاح الجديد
403	PARTNER_SUSPENDED	الحساب غير نشط — تواصل مع esimoa
403	INSUFFICIENT_SCOPE	طلب خارج نطاقات المفتاح
403	IP_NOT_ALLOWED	تم الاستدعاء من عنوان IP خارج قائمة السماح — أضف عنوان IP الصادر لخادمك
404	PRODUCT_NOT_FOUND	منتج غير معروف أو متوقف
429	RATE_LIMITED	تم تجاوز حد المعدل — أعد المحاولة بعد عدد الثواني المحدد في Retry-After

Rate limits#

ملاحظة

الحد الافتراضي لطلبات API الخاصة بـ B2B هو 20,000 طلب في الساعة لكل مفتاح.

تبدأ نافذة الـ 3,600 ثانية مع أول طلب، ويُطبَّق الحد لكل دقيقة أيضًا. تُحسب الحصص بعدد الاستدعاءات لا بحجم MB المنقولة. قد تغيّر الإعدادات التشغيلية الحصة.

X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset

تُظهر هذه الترويسات الحد بالساعة والاستدعاءات المتبقية ووقت إعادة التعيين (بثواني Unix). عند استنفاد الحد بالساعة يُرجَع HTTP 429 مع Retry-After بالثواني. لا تُحتسب الاستدعاءات المرفوضة بسبب الحد لكل دقيقة ضمن الحصة بالساعة.

الحد الافتراضي هو 300 طلب في الدقيقة لكل مفتاح (لكل نافذة مدتها 60 ثانية، مشتركة بين جميع الخوادم). يمكن لـ esimoa رفعه لكل حساب وفق عقدك. تتضمن كل استجابة موثّقة ترويسات الحصة.

X-RateLimit-Limit — الطلبات المسموح بها في الدقيقة
X-RateLimit-Remaining — الطلبات المتبقية في الفترة الحالية
X-RateLimit-Reset — وقت إعادة تعيين الفترة (ثوانٍ بتوقيت Unix)
Retry-After — عند 429، عدد الثواني قبل إعادة المحاولة

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000000

HTTP/1.1 429 Too Many Requests
Retry-After: 18
{ "statusCode": 429, "code": "RATE_LIMITED", "message": "Rate limit exceeded (300 requests per minute)." }

Retrying#

عند تلقي 429، انتظر عدد الثواني المحدد في Retry-After ثم أعد المحاولة.
أعد محاولة أخطاء 5xx بضع مرات مع تأخير أُسّي متزايد.
لن تتغير 400 و401 و403 و404 عند إعادة المحاولة — أصلح السبب.
يساعدك تخزين الكتالوج مؤقتًا لبضع دقائق على البقاء أقل من الحد بكثير.

javascript

async function b2bFetch(url, attempt = 0) {
  const res = await fetch(url, { headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY } });
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return b2bFetch(url, attempt + 1);
  }
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.message), { code: body.code, status: res.status });
  return body;
}

واجهة API للشركاء (B2B)

Errors & rate limits

Partner API error codes, per-key rate limits with X-RateLimit headers, and how to retry.

On this page

Error format
Error codes
Rate limits
Retrying

Error format#

json

// Success
{ "success": true, "data": ..., "total": 128, "page": 1, "limit": 20 }

// Error
{ "statusCode": 401, "code": "INVALID_API_KEY", "message": "The API key is invalid." }

ملاحظة

تستخدم أخطاء التحقق من الاستعلام (400) التنسيق القياسي { statusCode: 400, message: [...], error: "Bad Request" } دون رمز.

Error codes#

HTTP	code	المعنى والحل
401	API_KEY_REQUIRED	لم يتم إرسال مفتاح — أضف الترويسة X-API-Key
401	INVALID_API_KEY	مفتاح غير صالح الصيغة أو غير معروف — تأكد من أن النسخ لم يكن مبتورًا وأنه ليس مفتاح API العامة
401	KEY_REVOKED	مفتاح مُبطَل — أنشئ مفتاحًا جديدًا
401	KEY_EXPIRED	مفتاح منتهي الصلاحية (بما في ذلك المفتاح القديم بعد انتهاء فترة السماح للتدوير) — استخدم المفتاح الجديد
403	PARTNER_SUSPENDED	الحساب غير نشط — تواصل مع esimoa
403	INSUFFICIENT_SCOPE	طلب خارج نطاقات المفتاح
403	IP_NOT_ALLOWED	تم الاستدعاء من عنوان IP خارج قائمة السماح — أضف عنوان IP الصادر لخادمك
404	PRODUCT_NOT_FOUND	منتج غير معروف أو متوقف
429	RATE_LIMITED	تم تجاوز حد المعدل — أعد المحاولة بعد عدد الثواني المحدد في Retry-After

Rate limits#

ملاحظة

الحد الافتراضي لطلبات API الخاصة بـ B2B هو 20,000 طلب في الساعة لكل مفتاح.

X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset

X-RateLimit-Limit — الطلبات المسموح بها في الدقيقة
X-RateLimit-Remaining — الطلبات المتبقية في الفترة الحالية
X-RateLimit-Reset — وقت إعادة تعيين الفترة (ثوانٍ بتوقيت Unix)
Retry-After — عند 429، عدد الثواني قبل إعادة المحاولة

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000000

HTTP/1.1 429 Too Many Requests
Retry-After: 18
{ "statusCode": 429, "code": "RATE_LIMITED", "message": "Rate limit exceeded (300 requests per minute)." }

Retrying#

عند تلقي 429، انتظر عدد الثواني المحدد في Retry-After ثم أعد المحاولة.
أعد محاولة أخطاء 5xx بضع مرات مع تأخير أُسّي متزايد.
لن تتغير 400 و401 و403 و404 عند إعادة المحاولة — أصلح السبب.
يساعدك تخزين الكتالوج مؤقتًا لبضع دقائق على البقاء أقل من الحد بكثير.

javascript

async function b2bFetch(url, attempt = 0) {
  const res = await fetch(url, { headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY } });
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return b2bFetch(url, attempt + 1);
  }
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.message), { code: body.code, status: res.status });
  return body;
}