الأخطاء

يستخدم كل خطأ، عبر الـ API بأكمله، مغلّفًا واحدًا، بحيث يمكنك التعامل مع الإخفاقات بمسار كود واحد.

شكل الخطأ

غلاف الخطأ

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request was invalid.",
    "details": [
      { "path": "declaredNumber", "message": "must be E.164" }
    ]
  }
}

تطابق حالة HTTP الرمز code. الحقل details موجود فقط في أخطاء التحقّق.

رموز الأخطاء

الرمز	HTTP	متى
UNAUTHORIZED	401	مفتاح مفقود أو غير صالح.
FORBIDDEN	403	المفتاح يفتقر إلى النطاق المطلوب.
NOT_FOUND	404	لا يوجد مورد كهذا في حسابك.
VALIDATION_FAILED	400	كان جسم الطلب أو الاستعلام غير صالح.
CONFLICT	409	الإجراء يتعارض مع الحالة الحالية (مثل الإرسال من رقم غير متصل).
RATE_LIMITED	429	طلبات كثيرة جدًا. خفّف الوتيرة وأعِد المحاولة.
OUTBOUND_LIMIT	429	سقف المراسلة الباردة: بدأ هذا الرقم عددًا كبيرًا جدًا من المحادثات الجديدة خلال هذه الساعة. والردود لا تُحتسب أبدًا. انتظر المدة التي تحدّدها Retry-After، وأبقِ حجم الاتصالات الأولى معتدلًا.
SLOT_REQUIRED	402	ربط رقم يتطلّب خانة متاحة.
ACCOUNT_SUSPENDED	402	الحساب كله قيد الإيقاف المؤقت. وكل المسارات تردّ بهذا عدا تسجيل الدخول والفوترة. المفتاح صالح وإعادة المحاولة لن تفيد: تواصل معنا لاستعادة الوصول.
TRANSPORT_UNAVAILABLE	503	خدمة الاتصال غير متاحة لبرهة. أعِد المحاولة بعد قليل.
TRANSPORT_BUSY	503	خدمة الرسائل مشغولة. انتظر المدة التي تحدّدها ترويسة Retry-After ثم أعِد المحاولة، وكل ما صدر سابقًا يبقى صالحًا.
BILLING_UNAVAILABLE	503	لا يوجد في هذا النشر أي معالج مدفوعات مُهيّأ.
INTERNAL	500	خطأ غير متوقّع من جهتنا.

التمهّل وإعادة المحاولة

ثلاثة رموز تطلب منك الانتظار، ومعانيها مختلفة. فـ RATE_LIMITED يعني خفّف الوتيرة. وOUTBOUND_LIMIT يعني توقّف مدةً عن مراسلة أشخاص جدد: فالردود ما زالت تمرّ، والميزانية تخصّ الرقم لا مفتاحك. وTRANSPORT_BUSY يعني أن خدمة الرسائل تحدّ من وتيرتنا: إنه ضغط حِمل، لا عيب في طلبك، وكل ما صدر سابقًا يبقى صالحًا. وتحمل الرموز الثلاثة Retry-After بالثواني حين تكون المدة معروفة، فانتظر تلك المدة على الأقل.

429 Too Many Requests

{
  "error": {
    "code": "OUTBOUND_LIMIT",
    "message": "This number has started too many new conversations in the last hour."
  }
}

أخطاء التحقّق

بالنسبة لخطأ VALIDATION_FAILED، يسرد details كل حقل مخالف عبر path لتتمكّن من إظهار المشكلة بجوار الحقل الصحيح.

معالجة الأخطاء

const res = await fetch("https://api.sendveo.com/v1/numbers", options)
if (!res.ok) {
  const { error } = await res.json()
  if (error.code === "VALIDATION_FAILED") {
    for (const d of error.details ?? []) showFieldError(d.path, d.message)
  } else {
    showBanner(error.message)
  }
}