الأخطاء

تستخدم Authevo رموز حالة HTTP القياسية. تُغلَّف الاستجابات الناجحة ضمن كائن data، بينما تُعيد حالات الفشل كائن error يحتوي رمزًا قابلًا للقراءة آليًا ورسالة مقروءة للبشر. تغطّي الجداول أدناه كل رمز يمكن أن تُعيده نقاط النهاية العامة للإرسال والتحقق وTOTP — اعتمد دائمًا على حالة HTTP وعلى error.code في التفرّع، لا على الرسالة، فقد تتغيّر الرسائل.

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body/phone must match pattern \"^\\+[1-9]\\d{6,14}$\""
  }
}

عام ومصادقة

الحالة	الرمز	المعنى
`400`	`VALIDATION_ERROR`	جسم الطلب غير صحيح، أو يفتقد حقلًا إلزاميًا، أو رقم الهاتف ليس رقمًا صالحًا بصيغة E.164.
`401`	`INVALID_API_KEY`	ترويسة Authorization مفقودة أو المفتاح السري غير صالح.
`401`	`ACCOUNT_SUSPENDED`	حسابك موقوف ولا يمكنه استدعاء الـ API. تواصل مع الدعم.
`404`	`NOT_FOUND`	المورد المطلوب (مثل معرِّف طلب OTP) غير موجود أو لا يخص حسابك.
`429`	`RATE_LIMIT_EXCEEDED`	طلبات كثيرة جدًا. خفِّف الوتيرة وأعِد المحاولة بعد مهلة قصيرة.
`500`	`INTERNAL_ERROR`	فشل شيء ما من جانب Authevo. آمن إعادة المحاولة — هذه الأخطاء مُسجَّلة ومُراقَبة.

الإرسال والتحقق

الحالة	الرمز	المعنى
`400`	`INVALID_PHONE`	رقم الهاتف غير صالح أو غير قابل للوصول لهذه النقطة.
`400`	`OTP_NOT_FOUND`	انتهت صلاحية الرمز، أو استُخدم بالفعل، أو لم يُرسَل قط لهذا الرقم.
`409`	`IDEMPOTENCY_KEY_IN_PROGRESS`	لا يزال هناك طلب بنفس Idempotency-Key قيد المعالجة — انتظر انتهاءه بدلًا من إرسال محاولة ثالثة.
`409`	`TEMPLATE_NOT_READY`	قالب رسالة WhatsApp لم يُعتمَد بعد على الرقم المُرسِل. يتحوّل تلقائيًا إلى Telegram إذا كان المستلم قد ربط حسابه.
`409`	`CHANNEL_NOT_LINKED`	فشل التسليم عبر WhatsApp ولم يربط هذا المستلم Telegram بعد — لم يُسلَّم شيء في هذا الاستدعاء. اعرض له telegram_bot_url المُعاد؛ بمجرد أن ينقر Start في Telegram، يختلف السلوك حسب النقطة التي استدعيتها: /v1/otp/send تُسلِّم رمزًا جديدًا هناك تلقائيًا (لا حاجة لاستدعائها مجددًا)، أما /v1/otp/deliver فلا تفعل ذلك — لا يمكن لـ Authevo إعادة توليد رمز أنشأتَه أنت بنفسك، لذا أعد استدعاء /v1/otp/deliver بنفس الرمز بعد أن يربط حسابه. تفضّل تجنّب هذا الخطأ من الأساس؟ استدعِ نقطة ربط Telegram بشكل استباقي فور التسجيل.
`429`	`TOO_MANY_ATTEMPTS`	محاولات تحقق فاشلة كثيرة جدًا لهذا الرقم. انتظر قبل إعادة المحاولة.
`500`	`DELIVERY_FAILED`	تعذّر تسليم الرسالة عبر أي قناة. آمن إعادة المحاولة.
`503`	`TELEGRAM_UNAVAILABLE`	التحويل الاحتياطي إلى Telegram غير متاح حاليًا.

رقم WhatsApp المشترك من Authevo

الحالة	الرمز	المعنى
`400`	`CENTRAL_WHATSAPP_UNSUPPORTED_REGION`	هذه الجهة غير مُفعَّلة للإرسال عبر رقم WhatsApp المشترك من Authevo. تذكر رسالة الخطأ الجهات المُفعَّلة فعلًا، والقائمة الحالية منشورة في صفحة الأسعار. اربط حساب WhatsApp Business الخاص بك للإرسال إلى أي جهة أخرى.
`400`	`INTL_PRICING_NOT_CONFIGURED`	لا يوجد سعر مُهيَّأ لهذه الجهة على حسابك، لذلك يُرفَض الإرسال بدلًا من تحصيل مبلغ تخميني. اربط حساب WhatsApp Business الخاص بك، أو تواصل مع الدعم لتفعيل الجهة.
`400`	`INTL_PRICE_BELOW_COST`	يوجد سعر مُهيَّأ لهذه الجهة لكنه أقل من تكلفة التسليم الفعلية، لذلك يُوقَف الإرسال بدلًا من تنفيذه بخسارة. هذه مشكلة إعداد من جانبنا — تواصل مع الدعم.
`403`	`CENTRAL_WHATSAPP_CONNECT_REQUIRED`	استهلك حسابك حدَّه المتاح على رقم WhatsApp المشترك من Authevo. اربط حساب WhatsApp Business الخاص بك لمواصلة الإرسال — فليس عليه هذا الحد.
`429`	`CENTRAL_WHATSAPP_LIMIT`	بلغ حسابك حدَّ الإرسال بالساعة على رقم WhatsApp المشترك من Authevo. أعد المحاولة بعد انتهاء المدة، أو اربط حساب WhatsApp Business الخاص بك لإزالة الحد.
`503`	`CENTRAL_WHATSAPP_PAUSED`	الإرسال عبر رقم WhatsApp المشترك من Authevo متوقّف مؤقتًا، إمّا لحسابك أو على مستوى المنصّة بالكامل. أعد المحاولة قريبًا. أما الإرسال عبر حساب WhatsApp Business الخاص بك فلا يتأثر إطلاقًا.

مصادقة ثنائية (TOTP)

الحالة	الرمز	المعنى
`400`	`TOTP_NOT_ENROLLED`	لا يوجد تسجيل TOTP نشط لهذا الرقم للتحقق منه أو تعطيله.
`409`	`ALREADY_ENROLLED`	يملك هذا الرقم بالفعل تسجيل TOTP مؤكَّدًا. مرِّر replace: true لإصدار تسجيل جديد.
`429`	`TOO_MANY_ATTEMPTS`	محاولات تحقق فاشلة كثيرة جدًا لهذا الرقم. انتظر قبل إعادة المحاولة.
`503`	`TOTP_NOT_CONFIGURED`	TOTP غير متاح مؤقتًا من جانب Authevo.

الفوترة والرصيد

الحالة	الرمز	المعنى
`402`	`INSUFFICIENT_CREDITS`	رصيد حسابك أقل من المبلغ اللازم للإرسال — أضِف رصيدًا مدفوعًا مسبقًا للمتابعة (يلزم حدّ أدنى قدره $2).
`402`	`DEPOSIT_REQUIRED`	لم يشهد حسابك أي إيداع من قبل — أضِف رصيدًا مدفوعًا مسبقًا قبل أول عملية إرسال.
`402`	`FREE_TRIAL_EXHAUSTED`	استخدمت كل عمليات التحقق المجانية. أضِف رصيدًا لمواصلة الإرسال.
`429`	`SPEND_CAP_EXCEEDED`	بلغت الحدّ الأقصى للإنفاق في الساعة. يُعاد ضبطه تلقائيًا؛ ارفعه من لوحة التحكم إن كنت تصل إليه كثيرًا.
`500`	`BILLING_ERROR`	نجحت عملية التحقق نفسها، لكن فوترتها فشلت — من جانب Authevo لا جانبك. يُسجَّل ويُسوَّى تلقائيًا؛ نتيجة التحقق الناجحة تبقى قائمة.
`503`	`FREE_TRIAL_PAUSED`	الفترة المجانية متوقفة مؤقتًا على مستوى المنصة بالكامل. أعِد المحاولة قريبًا، أو أضِف رصيدًا للإرسال فورًا.

اعتمد دائمًا على حالة HTTP وعلى error.code في التفرّع، لا على الرسالة — فقد تتغيّر الرسائل.

حدود المعدّل

لكل عملية في الواجهة سياسة قبول على الخادم، مع حدود منفصلة للدفعات القصيرة والمعدل المستمر وضوابط للمستلم والحساب والمفتاح ومحاولات التحقق والإنفاق. عند بلوغ حد، انتظر عدد الثواني في Retry-After. تعرض RateLimit-Policy وX-Authevo-Rate-Tier حد الإرسال الإجمالي الفعلي لحسابك.

النطاق	الحد	النافذة الزمنية
رقم هاتف المستلم نفسه (الإرسال)	3 طلبات	10 دقائق
إعادة الإرسال من الحساب نفسه إلى المستلم نفسه	طلب واحد	30 ثانية
المستلم نفسه عبر جميع الحسابات	6 / 20 طلبًا	10 دقائق / 24 ساعة
مفتاح API نفسه (إرسال OTP أو التحقق)	300 طلب	دقيقة واحدة
الحساب أو مفتاح API نفسه (دفعة OTP قصيرة)	100 طلب (قياسي)	10 ثوانٍ
ساحة التجربة، المستلم نفسه	1 / 3 / 5 طلبات	دقيقة / 10 دقائق / 24 ساعة
عنوان IP غير الموثق (حاجز الإرسال)	10–40 طلبًا	ساعة واحدة
محاولات تحقق فاشلة، لنفس رقم الهاتف	5 محاولات	حظر لمدة 15 دقيقة

ينطبق صف 10–40 في الساعة فقط عندما لا يملك الطلب هوية حساب موثقة. تُعزل حركة الخوادم الموثقة عند الحافة ببصمة مبهمة للمفتاح، ولها حاجز لكل حساب يساوي 60 ضعف معدله المستمر، فلا تستهلك حسابات تشترك في عنوان خروج سحابي حصة بعضها. الحد القياسي 300/دقيقة باستمرار و100/10 ثوانٍ كدفعة و18,000/ساعة. تتطلب مستويات 1,000 و5,000 أو المستوى المخصص مراجعة الرصيد والسجل الأمني والحركة المتوقعة وجودة التسليم وحساب WABA مملوكًا للعميل، وتنتهي تلقائيًا. لا يمكن إلغاء حدود المستلم أو حدود الأمان العامة.

هل تحتاج إلى معدل أعلى؟

تعرض صفحة «الاستخدام والحدود» الموثقة المستوى الفعلي والاستخدام المباشر لنوافذ الاندفاع والدقيقة والساعة مع أوقات إعادة ضبط منفصلة، وأحداث التقييد المنقّحة، والأهلية. قدّم منها أدلة حركة الإنتاج لمراجعة بشرية. تنتهي المستويات المعتمدة تلقائيًا، ولا يتغير سوى المعدل الإجمالي؛ إذ تبقى فترات تهدئة المستلم وحدود أمان المنصة مطبّقة.

فتح الاستخدام والحدود

الحدّ الآمن

إضافةً إلى الحدود أعلاه، يرصد «الحدّ الآمن» معدّل نجاح حسابك الفعلي: ثلاثة أيام متتالية بمعدّل نجاح تحقق أقل من 55% خلال 24 ساعة تنقل حسابك من الدفع مقابل النجاح إلى مستوى الدفع لكل رسالة حتى يتعافى. إنه حاجز أمان ضد إساءة الاستخدام المستمرة أو تكامل معطوب يُضخّم فاتورتك بصمت — تلقائي، دون أي إعداد.

Idempotency

أرسِل ترويسة Idempotency-Key مع POST /v1/otp/send أو POST /v1/otp/deliver لجعل إعادة محاولات الشبكة آمنة — تُعيد المحاولة بنفس المفتاح تشغيل الاستجابة الأصلية بدلًا من إرسال (وفوترة) رسالة ثانية.

Idempotency-Key: 5b6b4c9e-6e0a-4b7a-9b7a-2f2b6a7c9e10

ولِّد مفتاحًا جديدًا لكل محاولة إرسال منطقية (UUID خيار جيد)، وأعِد استخدامه فقط عند إعادة محاولة تلك المحاولة بعينها. تكون المفاتيح خاصة بحسابك ويُحتفَظ بها لمدة 24 ساعة — إعادة محاولة بنفس المفتاح أثناء معالجة الطلب الأصلي تُعيد فورًا 409 IDEMPOTENCY_KEY_IN_PROGRESS بدلًا من التسابق معه.

الترويسة اختيارية بالكامل — تعمل الطلبات بدونها تمامًا كما كانت. تستحق الإضافة أينما كان منطق إعادة المحاولة لديك قد يُعيد إرسال الطلب نفسه بعد انتهاء المهلة. وتقبلها حزمة Node الرسمية عبر خيار idempotencyKey في otp.send و‏otp.deliver (الإصدار 0.3.0 فأحدث).