Guides
حدود المعدل والأخطاء
Public API per-account rate limits, error response format, status codes and caching guidance.
On this page
Rate limits#
ملاحظة
تتشارك API العامة وMCP المصادق عليه حصة بالساعة لكل شريك (20,000 افتراضيًا). لا تؤدي إضافة المفاتيح أو تدويرها إلى زيادتها.
تبدأ نافذة الـ 3,600 ثانية مع أول طلب، ويُطبَّق الحد لكل دقيقة أيضًا. تُحسب الحصص بعدد الاستدعاءات لا بحجم MB المنقولة. قد تغيّر الإعدادات التشغيلية الحصة.
تقبل دفعات MCP حتى 100 رسالة، وتُحتسب كل رسالة كاستدعاء واحد. الدفعة التي تتجاوز الحصة المتاحة تُرجع 429 قبل التنفيذ.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
تُظهر هذه الترويسات الحد بالساعة والاستدعاءات المتبقية ووقت إعادة التعيين (بثواني Unix). عند استنفاد الحد بالساعة يُرجَع HTTP 429 مع Retry-After بالثواني. لا تُحتسب الاستدعاءات المرفوضة بسبب الحد لكل دقيقة ضمن الحصة بالساعة.
الحد الافتراضي لكل حساب شريك هو 600 طلب في الدقيقة. عند تجاوزه ستتلقى 429 rate_limited.
البقشيش
Status codes#
| HTTP | المعنى |
|---|---|
| 200 | تم بنجاح |
| 400 | معلمات غير صالحة |
| 401 invalid_api_key | مفتاح مفقود أو خاطئ أو ملغى |
| 404 | معرّف eSIM غير معروف |
| 429 rate_limited | تم تجاوز حد المعدل |
Error format#
// 401 — missing, invalid or revoked key
{
"error": "invalid_api_key",
"message": "Missing or invalid API key. Create one at https://www.esimoa.com/developers/dashboard"
}
// 429 — too many requests for this key
{ "error": "rate_limited", "message": "Rate limit exceeded (600 requests per minute)." }
// 400 — invalid parameters / 404 — unknown eSIM id
{ "statusCode": 404, "message": "eSIM not found", "error": "Not Found" }Caching#
تتغير الأسعار كثيرًا — خزّن نتائج البحث مؤقتًا لبضع دقائق كحد أقصى.