الأخطاء والحدود
شكل الخطأ الموحد، وكل رموز الأخطاء، ومعرّف الطلب، وحدود الطلبات لكل خطة، وحدود عمليات البحث والعدّ، والحدود اليومية، والصفحات، وإعادة المحاولة الآمنة.
شكل واحد للخطأ
كل إجابة خطأ لها الشكل نفسه. اقرأ error.code لتقرر ما تفعله، واعرض error.message على الأشخاص. الرسالة جملة واحدة واضحة.
{
"error": {
"code": "insufficient_credits",
"message": "Revealing these people costs 1 credit each and the account has none left. Pick a plan at https://argorant.com/pricing.",
"details": { "needed": 25, "balance": 0 }
},
"request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
"detail": "..."
}يحمل detail الصيغة الأقدم للخطأ من أجل البرامج العميلة المكتوبة قبل هذا الشكل. على الكود الجديد أن يقرأ error.
رموز الأخطاء
| الرمز | الحالة | ما يعنيه وما يجب فعله |
|---|---|---|
invalid_request | 400 | ينقص الطلب شيء ما أو توجد قيمة خاطئة. توضح الرسالة ما يجب إصلاحه. |
launch_blocked | 400 | لا يمكن إطلاق الحملة بعد. يسرد details.blockers ما هو ناقص. |
unauthorized | 401 | لا يوجد مفتاح API، أو المفتاح خاطئ أو ملغى. |
api_key_required | 401 | يحتاج هذا المسار إلى مفتاح API أو تسجيل دخول عبر الموصِّل، لا إلى جلسة متصفح. |
plan_required | 402 | خطة الحساب لا تتضمن هذا. تذكر الرسالة الخطة التي تتضمنه. يتلقى مفتاح الحساب الذي لا خطة له ولا أرصدة هذا الخطأ في كل استدعاء. |
insufficient_credits | 402 | الأرصدة لا تكفي لهذا الاستدعاء. يوضح details عدد الأرصدة المطلوبة. لم يُخصم أي شيء. |
scope_missing | 403 | ينقص المفتاح نطاق صلاحيات يحتاجه هذا الاستدعاء. أنشئ مفتاحًا بهذا النطاق. |
permission_missing | 403 | دورك في مساحة العمل لا يسمح بهذا الإجراء. |
forbidden | 403 | هذا الإجراء غير مسموح به لهذا الحساب. |
not_found | 404 | لا يوجد عنصر كهذا في مساحة عملك. العناصر التابعة لمساحات عمل أخرى تُجيب بالطريقة نفسها. |
route_not_found | 404 | لا توجد نقطة نهاية كهذه. قارن المسار بالمرجع. |
method_not_allowed | 405 | المسار موجود، لكن ليس مع طريقة HTTP هذه. يسرد details.allowed الطرق المتاحة. |
conflict | 409 | حالة العنصر لا تسمح بهذا، مثل حذف حملة قيد التشغيل. |
idempotency_conflict | 409 | استُخدم هذا Idempotency-Key من قبل مع جسم طلب مختلف. |
idempotency_in_progress | 409 | لا يزال طلب بهذا Idempotency-Key قيد التنفيذ. انتظر ثم أعد المحاولة. |
gone | 410 | انتهت صلاحية العنصر، مثل ملف تصدير تجاوز مدة الاحتفاظ به. |
quote_expired | 410 | عرض السعر قديم جدًا. احصل على عرض سعر جديد وأكّد مرة أخرى. |
validation_error | 422 | أحد الحقول من نوع خاطئ أو مفقود. يسرد details.fields كل مشكلة. |
access_key_activation_required | 428 | مفتاح الوصول المدعو هذا غير مفعّل بعد. أكّد البريد الإلكتروني في details.claim_url أولًا. |
rate_limited | 429 | طلبات كثيرة جدًا في هذه الدقيقة أو خلال 10 ثوانٍ، أو عمليات بحث وعدّ كثيرة جدًا في هذه الدقيقة، أو كشف أكثر من 200 شخص في الدقيقة. انتظر عدد الثواني المذكور في Retry-After. |
daily_limit_reached | 429 | استُنفد حد يومي: حد المفتاح لهذا النوع من الاستدعاءات، أو عدد عناوين البريد الجديدة اليومي لحساب بلا خطة. يذكره details.action. يُعاد ضبطه عند منتصف الليل بتوقيت UTC. |
internal_error | 500 | حدث خطأ من جهتنا. أعد المحاولة؛ واذكر معرّف الطلب إذا استمر الخطأ. |
unavailable | 503 | جزء من الخدمة مشغول أو متوقف مؤقتًا. أعد المحاولة بعد دقيقة. |
confirmation_required | 400 | يحتاج الطلب إلى confirmed=true، ولا يُرسل إلا بعد موافقة الشخص الذي يدفع. |
invalid_webhook_url | 400 | يجب أن يكون عنوان Webhook عنوانًا عامًا يبدأ بـ https://. |
invalid_webhook_events | 400 | اسم حدث غير معروف أو لم يُحدد أي حدث. يسرد details.invalid الأسماء غير المعروفة. |
webhook_limit_reached | 400 | لديك 10 Webhooks مفعّلة، أو 50 إجمالًا مع المعطّلة. احذف واحدًا أو عطّل واحدًا أولًا. لكل عضو في الفريق Webhooks خاصة به. |
event_not_subscribed | 400 | ذكر استدعاء اختباري حدثًا لا يستقبله Webhook. يسرد details.events الأحداث التي يستقبلها. |
company_credits_required | 402 | الملف الكامل للشركة يكلّف أرصدة، وأرصدة الحساب غير كافية. يحمل details.teaser الجزء المجاني؛ ولم يُخصم أي شيء. |
search_busy | 503 | البحث مشغول الآن. حاول مرة أخرى بعد بضع ثوانٍ. |
phones_not_in_plan | 402 | أرقام الهواتف متاحة مع خطة Pro. لم يُخصم أي شيء. |
card_not_charged | 402 | لم يُخصم المبلغ من البطاقة المحفوظة. لم يُشترَ أي شيء؛ ادفع عبر رابط دفع بدلًا من ذلك. |
owner_only | 403 | لا يستطيع ذلك إلا مالك مساحة العمل، مثل طلب صناديق البريد أو إلغائها. |
quote_not_found | 404 | عرض السعر غير موجود أو يخص شخصًا آخر. احصل على عرض سعر جديد. |
charge_in_progress | 409 | يجري الآن خصم مبلغ عرض السعر هذا. تحقق من الطلب بعد لحظات. |
not_enough_names | 409 | لم يُعثر على عدد كافٍ من أسماء النطاقات المتاحة. أرسل بعض النطاقات بنفسك. |
not_paid | 409 | الطلب لم يُدفع بعد، لذا لا يوجد ما يُلغى. |
reason_required | 422 | يتطلب إلغاء صناديق البريد سببًا من الخيارات المدرجة. |
not_connected | 409 | هذه الأداة غير متصلة بعد. اربطها أولًا في الإعدادات، الأدوات المتصلة. |
unsupported_tool | 409 | لا تستطيع هذه الأداة المتصلة استقبال الأشخاص مباشرة. أرسل إليها ملف تصدير من صفحة عمليات التصدير بدلًا من ذلك. |
tool_key_rejected | 409 | لم تقبل الأداة المتصلة المفتاح المحفوظ. اربطها مرة أخرى في الإعدادات، الأدوات المتصلة. |
price_mismatch | 409 | السعر الذي عرضته على الشخص ليس السعر الوارد في عرض السعر. اعرض السعر الوارد في العرض واسأل مرة أخرى. |
quote_other_session | 409 | أُنشئ عرض السعر بمفتاح أو اتصال آخر. اطلب عرض سعر جديدًا هنا وأكّد مرة أخرى. |
export_failed | 409 | لم يكتمل التصدير، لذا لا يوجد ما يُرسل. شغّل التصدير مرة أخرى. |
sign_in_failed | 422 | لم يقبل خادم البريد تسجيل الدخول، لذا لم يُربط صندوق البريد. يوضح details.test ما الخطأ الذي حدث في الإرسال وفي قراءة الردود. |
campaign_not_started | 409 | الحملة مسودة، لذا لا يوجد ما يُوقف مؤقتًا. أطلقها أولًا. |
finder_rate_limit | 429 | أكثر من 30 عملية بحث فردية عن البريد الإلكتروني في هذه الدقيقة. انتظر عدد الثواني المذكور في Retry-After. |
finder_daily_limit | 429 | 2,000 عملية بحث عن البريد الإلكتروني اليوم. يُعاد ضبط الحد عند منتصف الليل بتوقيت UTC. |
finder_miss_rate_throttle | 429 | معظم عمليات البحث الأخيرة لم تجد شيئًا، لذا أُبطئت عمليات البحث إلى 20 في الساعة لبعض الوقت. تحقق من الأسماء والنطاقات. |
تضيف بعض العمليات رمزًا خاصًا بها، مثل confirmation_required أو quote_not_found. تسرد كل عملية رموزها في المرجع. تعامل مع أي رمز لا تعرفه حسب حالة HTTP الخاصة به.
معرّف الطلب
كل إجابة تحمل الترويسة X-Request-Id، وكل خطأ يكررها في request_id. أرسل معرّفك الخاص في الترويسة X-Request-Id (من 8 إلى 64 حرفًا أو رقمًا أو نقطة أو شرطة أو شرطة سفلية) لتجد الاستدعاء في سجلاتك. اذكر المعرّف عندما تطلب المساعدة.
الطلبات في الدقيقة
يمكن لكل مفتاح إرسال هذا العدد من الطلبات في الدقيقة، وحتى الرقم الثاني في أي 10 ثوانٍ.
| الخطة | الطلبات في الدقيقة | خلال 10 ثوانٍ |
|---|---|---|
| بلا خطة، مفتاح API أو CLI | 30 | 15 |
| بلا خطة، مساعد ذكاء اصطناعي | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1,200 | 300 |
تشمل حالة بلا خطة أول 7 أيام لحساب لم يختر خطة بعد، والحسابات التي تستخدم أرصدة اشترتها سابقًا. الفترة التجريبية لخطة ما لها حدود تلك الخطة. يتلقى مفتاح الحساب الذي لا خطة له ولا أرصدة 402 plan_required في كل استدعاء، بما في ذلك GET /api/v1/account.
كل إجابة على استدعاء بمفتاح تحمل X-RateLimit-Limit (الطلبات في الدقيقة) وX-RateLimit-Remaining (الطلبات المتبقية في هذه الدقيقة) وX-RateLimit-Reset (الثواني حتى تبدأ الدقيقة من جديد). إذا تجاوزت أيًا من الحدين تتلقى 429 rate_limited مع الترويسة Retry-After. انتظر هذا العدد من الثواني، ثم حاول مرة أخرى.
لكشف الأشخاص حد إضافي في كل الخطط: يستطيع الحساب كشف ما يصل إلى 200 شخص في الدقيقة. إذا تجاوزته تتلقى 429 rate_limited أيضًا.
عمليات البحث والعدّ
عمليات البحث والعدّ والمعاينات مجانية. وهي محدودة لكل حساب، عبر جميع مفاتيحه والموصِّل، لذا لا يضيف مفتاح ثانٍ أي زيادة.
| الخطة | في الدقيقة | عمليات العدّ يوميًا | صفوف المعاينة يوميًا |
|---|---|---|---|
| بلا خطة، مفتاح API أو CLI | 10 | 500 | 500 |
| بلا خطة، مساعد ذكاء اصطناعي | 20 | 1,000 | 1,000 |
| Starter | 30 | بلا حد | بلا حد |
| Pro | 60 | بلا حد | بلا حد |
| Scale | 90 | بلا حد | بلا حد |
| Hyperscale | 120 | بلا حد | بلا حد |
بلا خطة، تحمل عمليات البحث والعدّ أيضًا X-RateLimit-Daily-Limit وX-RateLimit-Daily-Remaining. تضم المعاينة ما يصل إلى 10 أشخاص في كل استدعاء.
الحدود اليومية لكل مفتاح
بلا خطة، لكل مفتاح أيضًا حدود يومية. مع خطة، لا يوجد حد يومي إلا للباحث عن البريد الإلكتروني؛ أما الباقي فتحدّه الأرصدة. يُعاد ضبط الحدود اليومية عند منتصف الليل بتوقيت UTC. يعرض GET /api/v1/account ما تبقى اليوم.
| ماذا | يوميًا | لكل استدعاء |
|---|---|---|
| الأشخاص المكشوفون، حسب الفلاتر | 100 (بلا حد مع خطة) | 25 |
| صفوف التصدير | 50,000 (بلا حد مع خطة) | 50,000 لكل ملف، و500,000 لكل دفعة |
| عمليات البحث عن البريد الإلكتروني | 2,000 | 30 في الدقيقة، وقوائم حتى 10,000 صف |
يجد الحساب الذي لا خطة له أيضًا ما يصل إلى 10 عناوين بريد جديدة يوميًا إجمالًا: عمليات الكشف ونتائج الباحث عن البريد الإلكتروني وصفوف التصدير تُحتسب معًا، والبريد الذي كان لديه من قبل لا يُحتسب.
إذا تجاوزت حدًا يوميًا تتلقى 429 daily_limit_reached. إذا أردت أشخاصًا أكثر من حد الكشف اليومي، فاحفظ قائمة أو صدّرها أو أضفها إلى حملة؛ فهذه الطرق مصممة لآلاف الأشخاص. يُجيب الباحث عن البريد الإلكتروني برموزه الخاصة: finder_rate_limit (في الدقيقة) وfinder_daily_limit (في اليوم) وfinder_miss_rate_throttle (معظم عمليات البحث لم تجد شيئًا).
الصفحات
كل قائمة تقبل limit وcursor. تحتفظ الإجابة بمفتاحها الخاص (مثل campaigns أو people) وتضيف total وlimit وoffset وnext_cursor وhas_more. مرّر next_cursor في cursor للحصول على الصفحة التالية؛ وتكون قيمته null في الصفحة الأخيرة. يعمل offset أيضًا، إذا كنت تفضّل عدّ الصفوف بنفسك.
بعض القوائم تنتهي مبكرًا أو تُقسّم إلى صفحات بطريقتها الخاصة. الأشخاص في الحملة يُقسّمون إلى صفحات باستخدام after بقيمة next_after، بترتيب ثابت، ولا تحمل هذه الصفحات next_cursor. وتُقسّم ردود الحملة بالطريقة نفسها باستخدام after وnext_after. تصل قائمة الحملات إلى أول 500 حملة؛ ويتنقل cursor بين صفحاتها ضمن هذا العدد. ويقبل صندوق الوارد وردود الحملة والأشخاص في الحملة أيضًا فلتر تاريخ (updated_after وreceived_after، أو created_after) بصيغة ISO 8601.
curl "https://app.argorant.com/api/v1/campaigns?limit=25" -H "Authorization: Bearer $ARGORANT_API_KEY"
curl "https://app.argorant.com/api/v1/campaigns?limit=25&cursor=bzoyNQ" -H "Authorization: Bearer $ARGORANT_API_KEY"عندما تكون قيمة total_is_estimate هي true، فإن total هو الحد الأدنى الموجود، مثلًا عندما تبلغ القائمة أكبر حجم لها.
إعادة المحاولة الآمنة
أرسل الترويسة Idempotency-Key مع أي عملية كتابة: الإنشاء والتغيير والحذف والرد وإعادة التوجيه وكل ما يستهلك أرصدة أو مالًا. استخدم قيمة عشوائية جديدة لكل إجراء جديد، والقيمة نفسها عند إعادة محاولته.
- المفتاح نفسه مع جسم الطلب نفسه خلال 24 ساعة يُرجع الإجابة الأولى، مع الترويسة
Idempotent-Replayed: true. لا يُنفّذ أي شيء مرتين. - المفتاح نفسه مع جسم طلب مختلف يُجيب بـ
409 idempotency_conflict. - ما دام الطلب الأول قيد التنفيذ، تُجيب إعادة المحاولة بـ
409 idempotency_in_progress. انتظر لحظة ثم حاول مرة أخرى. - الأخطاء لا تُخزّن، لذا يمكنك إصلاح المشكلة وإعادة المحاولة بالمفتاح نفسه.
curl -X POST "https://app.argorant.com/api/v1/exports" \
-H "Authorization: Bearer $ARGORANT_API_KEY" \
-H "Idempotency-Key: export-cfo-germany-2026-10-07" \
-H "Content-Type: application/json" \
-d '{"filters":{"title":"CFO","country":"Germany"},"limit":500}'الحملات التي لا يمكن إطلاقها
يُجيب POST /api/v1/campaigns/{id}/launch بـ launch_blocked ما دام هناك شيء ناقص، مثل بريد إلكتروني، أو صندوق بريد لا تزال لديه سعة اليوم، أو أشخاص. يسرد details.blockers كل نقص بكلمات واضحة. ويعرض GET /api/v1/campaigns/{id} القائمة نفسها باسم launch_blockers، حتى تتمكن من إصلاحها قبل المحاولة.