الأخطاء

تستخدم 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 مفقودة أو المفتاح السري غير صالح.
`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 لهذا الرقم أولًا.
`429`	`TOO_MANY_ATTEMPTS`	محاولات تحقق فاشلة كثيرة جدًا لهذا الرقم. انتظر قبل إعادة المحاولة.
`500`	`DELIVERY_FAILED`	تعذّر تسليم الرسالة عبر أي قناة. آمن إعادة المحاولة.
`503`	`TELEGRAM_UNAVAILABLE`	التحويل الاحتياطي إلى Telegram غير متاح حاليًا.

مصادقة ثنائية (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 في التفرّع، لا على الرسالة — فقد تتغيّر الرسائل.

حدود المعدّل

تخضع الطلبات لتحديد المعدّل لكل رقم هاتف ولكل عنوان IP مصدر. عند تجاوز حد ما تُجيب الواجهة بـ 429 RATE_LIMIT_EXCEEDED — تراجَع وأعِد المحاولة بعد مهلة قصيرة. هذه هي الأرقام الحقيقية والحالية، لا أرقام توضيحية.

النطاق	الحد	النافذة الزمنية
رقم هاتف المستلم نفسه (الإرسال)	3 طلبات	10 دقائق
عنوان IP المصدر نفسه	10 طلبات	ساعة واحدة
محاولات تحقق فاشلة، لنفس رقم الهاتف	5 محاولات	حظر لمدة 15 دقيقة

الحدّ الآمن

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

Idempotency

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

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

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

الترويسة اختيارية بالكامل — تعمل الطلبات بدونها تمامًا كما كانت. تستحق الإضافة أينما كان منطق إعادة المحاولة لديك قد يُعيد إرسال الطلب نفسه بعد انتهاء المهلة.