ArgorantDocs

الأخطاء والحدود

شكل الخطأ الموحد، وكل رموز الأخطاء، ومعرّف الطلب، وحدود الطلبات لكل خطة، وحدود عمليات البحث والعدّ، والحدود اليومية، والصفحات، وإعادة المحاولة الآمنة.

شكل واحد للخطأ

كل إجابة خطأ لها الشكل نفسه. اقرأ error.code لتقرر ما تفعله، واعرض error.message على الأشخاص. الرسالة جملة واحدة واضحة.

JSON
{
  "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_request400ينقص الطلب شيء ما أو توجد قيمة خاطئة. توضح الرسالة ما يجب إصلاحه.
launch_blocked400لا يمكن إطلاق الحملة بعد. يسرد details.blockers ما هو ناقص.
unauthorized401لا يوجد مفتاح API، أو المفتاح خاطئ أو ملغى.
api_key_required401يحتاج هذا المسار إلى مفتاح API أو تسجيل دخول عبر الموصِّل، لا إلى جلسة متصفح.
plan_required402خطة الحساب لا تتضمن هذا. تذكر الرسالة الخطة التي تتضمنه. يتلقى مفتاح الحساب الذي لا خطة له ولا أرصدة هذا الخطأ في كل استدعاء.
insufficient_credits402الأرصدة لا تكفي لهذا الاستدعاء. يوضح details عدد الأرصدة المطلوبة. لم يُخصم أي شيء.
scope_missing403ينقص المفتاح نطاق صلاحيات يحتاجه هذا الاستدعاء. أنشئ مفتاحًا بهذا النطاق.
permission_missing403دورك في مساحة العمل لا يسمح بهذا الإجراء.
forbidden403هذا الإجراء غير مسموح به لهذا الحساب.
not_found404لا يوجد عنصر كهذا في مساحة عملك. العناصر التابعة لمساحات عمل أخرى تُجيب بالطريقة نفسها.
route_not_found404لا توجد نقطة نهاية كهذه. قارن المسار بالمرجع.
method_not_allowed405المسار موجود، لكن ليس مع طريقة HTTP هذه. يسرد details.allowed الطرق المتاحة.
conflict409حالة العنصر لا تسمح بهذا، مثل حذف حملة قيد التشغيل.
idempotency_conflict409استُخدم هذا Idempotency-Key من قبل مع جسم طلب مختلف.
idempotency_in_progress409لا يزال طلب بهذا Idempotency-Key قيد التنفيذ. انتظر ثم أعد المحاولة.
gone410انتهت صلاحية العنصر، مثل ملف تصدير تجاوز مدة الاحتفاظ به.
quote_expired410عرض السعر قديم جدًا. احصل على عرض سعر جديد وأكّد مرة أخرى.
validation_error422أحد الحقول من نوع خاطئ أو مفقود. يسرد details.fields كل مشكلة.
access_key_activation_required428مفتاح الوصول المدعو هذا غير مفعّل بعد. أكّد البريد الإلكتروني في details.claim_url أولًا.
rate_limited429طلبات كثيرة جدًا في هذه الدقيقة أو خلال 10 ثوانٍ، أو عمليات بحث وعدّ كثيرة جدًا في هذه الدقيقة، أو كشف أكثر من 200 شخص في الدقيقة. انتظر عدد الثواني المذكور في Retry-After.
daily_limit_reached429استُنفد حد يومي: حد المفتاح لهذا النوع من الاستدعاءات، أو عدد عناوين البريد الجديدة اليومي لحساب بلا خطة. يذكره details.action. يُعاد ضبطه عند منتصف الليل بتوقيت UTC.
internal_error500حدث خطأ من جهتنا. أعد المحاولة؛ واذكر معرّف الطلب إذا استمر الخطأ.
unavailable503جزء من الخدمة مشغول أو متوقف مؤقتًا. أعد المحاولة بعد دقيقة.
confirmation_required400يحتاج الطلب إلى confirmed=true، ولا يُرسل إلا بعد موافقة الشخص الذي يدفع.
invalid_webhook_url400يجب أن يكون عنوان Webhook عنوانًا عامًا يبدأ بـ https://.
invalid_webhook_events400اسم حدث غير معروف أو لم يُحدد أي حدث. يسرد details.invalid الأسماء غير المعروفة.
webhook_limit_reached400لديك 10 Webhooks مفعّلة، أو 50 إجمالًا مع المعطّلة. احذف واحدًا أو عطّل واحدًا أولًا. لكل عضو في الفريق Webhooks خاصة به.
event_not_subscribed400ذكر استدعاء اختباري حدثًا لا يستقبله Webhook. يسرد details.events الأحداث التي يستقبلها.
company_credits_required402الملف الكامل للشركة يكلّف أرصدة، وأرصدة الحساب غير كافية. يحمل details.teaser الجزء المجاني؛ ولم يُخصم أي شيء.
search_busy503البحث مشغول الآن. حاول مرة أخرى بعد بضع ثوانٍ.
phones_not_in_plan402أرقام الهواتف متاحة مع خطة Pro. لم يُخصم أي شيء.
card_not_charged402لم يُخصم المبلغ من البطاقة المحفوظة. لم يُشترَ أي شيء؛ ادفع عبر رابط دفع بدلًا من ذلك.
owner_only403لا يستطيع ذلك إلا مالك مساحة العمل، مثل طلب صناديق البريد أو إلغائها.
quote_not_found404عرض السعر غير موجود أو يخص شخصًا آخر. احصل على عرض سعر جديد.
charge_in_progress409يجري الآن خصم مبلغ عرض السعر هذا. تحقق من الطلب بعد لحظات.
not_enough_names409لم يُعثر على عدد كافٍ من أسماء النطاقات المتاحة. أرسل بعض النطاقات بنفسك.
not_paid409الطلب لم يُدفع بعد، لذا لا يوجد ما يُلغى.
reason_required422يتطلب إلغاء صناديق البريد سببًا من الخيارات المدرجة.
not_connected409هذه الأداة غير متصلة بعد. اربطها أولًا في الإعدادات، الأدوات المتصلة.
unsupported_tool409لا تستطيع هذه الأداة المتصلة استقبال الأشخاص مباشرة. أرسل إليها ملف تصدير من صفحة عمليات التصدير بدلًا من ذلك.
tool_key_rejected409لم تقبل الأداة المتصلة المفتاح المحفوظ. اربطها مرة أخرى في الإعدادات، الأدوات المتصلة.
price_mismatch409السعر الذي عرضته على الشخص ليس السعر الوارد في عرض السعر. اعرض السعر الوارد في العرض واسأل مرة أخرى.
quote_other_session409أُنشئ عرض السعر بمفتاح أو اتصال آخر. اطلب عرض سعر جديدًا هنا وأكّد مرة أخرى.
export_failed409لم يكتمل التصدير، لذا لا يوجد ما يُرسل. شغّل التصدير مرة أخرى.
sign_in_failed422لم يقبل خادم البريد تسجيل الدخول، لذا لم يُربط صندوق البريد. يوضح details.test ما الخطأ الذي حدث في الإرسال وفي قراءة الردود.
campaign_not_started409الحملة مسودة، لذا لا يوجد ما يُوقف مؤقتًا. أطلقها أولًا.
finder_rate_limit429أكثر من 30 عملية بحث فردية عن البريد الإلكتروني في هذه الدقيقة. انتظر عدد الثواني المذكور في Retry-After.
finder_daily_limit4292,000 عملية بحث عن البريد الإلكتروني اليوم. يُعاد ضبط الحد عند منتصف الليل بتوقيت UTC.
finder_miss_rate_throttle429معظم عمليات البحث الأخيرة لم تجد شيئًا، لذا أُبطئت عمليات البحث إلى 20 في الساعة لبعض الوقت. تحقق من الأسماء والنطاقات.

تضيف بعض العمليات رمزًا خاصًا بها، مثل confirmation_required أو quote_not_found. تسرد كل عملية رموزها في المرجع. تعامل مع أي رمز لا تعرفه حسب حالة HTTP الخاصة به.

معرّف الطلب

كل إجابة تحمل الترويسة X-Request-Id، وكل خطأ يكررها في request_id. أرسل معرّفك الخاص في الترويسة X-Request-Id (من 8 إلى 64 حرفًا أو رقمًا أو نقطة أو شرطة أو شرطة سفلية) لتجد الاستدعاء في سجلاتك. اذكر المعرّف عندما تطلب المساعدة.

الطلبات في الدقيقة

يمكن لكل مفتاح إرسال هذا العدد من الطلبات في الدقيقة، وحتى الرقم الثاني في أي 10 ثوانٍ.

الخطةالطلبات في الدقيقةخلال 10 ثوانٍ
بلا خطة، مفتاح API أو CLI3015
بلا خطة، مساعد ذكاء اصطناعي6020
Starter6015
Pro24060
Scale600150
Hyperscale1,200300

تشمل حالة بلا خطة أول 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 أو CLI10500500
بلا خطة، مساعد ذكاء اصطناعي201,0001,000
Starter30بلا حدبلا حد
Pro60بلا حدبلا حد
Scale90بلا حدبلا حد
Hyperscale120بلا حدبلا حد

بلا خطة، تحمل عمليات البحث والعدّ أيضًا X-RateLimit-Daily-Limit وX-RateLimit-Daily-Remaining. تضم المعاينة ما يصل إلى 10 أشخاص في كل استدعاء.

الحدود اليومية لكل مفتاح

بلا خطة، لكل مفتاح أيضًا حدود يومية. مع خطة، لا يوجد حد يومي إلا للباحث عن البريد الإلكتروني؛ أما الباقي فتحدّه الأرصدة. يُعاد ضبط الحدود اليومية عند منتصف الليل بتوقيت UTC. يعرض GET /api/v1/account ما تبقى اليوم.

ماذايوميًالكل استدعاء
الأشخاص المكشوفون، حسب الفلاتر100 (بلا حد مع خطة)25
صفوف التصدير50,000 (بلا حد مع خطة)50,000 لكل ملف، و500,000 لكل دفعة
عمليات البحث عن البريد الإلكتروني2,00030 في الدقيقة، وقوائم حتى 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.

Shell
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. انتظر لحظة ثم حاول مرة أخرى.
  • الأخطاء لا تُخزّن، لذا يمكنك إصلاح المشكلة وإعادة المحاولة بالمفتاح نفسه.
Shell
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، حتى تتمكن من إصلاحها قبل المحاولة.

في هذه الصفحة