تخطَّ إلى المحتوى

الأخطاء

كل استدعاء فاشل للواجهة البرمجية يرمي SMSFabricError بعد أن تنفد محاولات العميل. ويرمي التحقق من خطافات الويب SignatureVerificationError. كلاهما يرث من Error، فيعمل instanceof في ESM وCommonJS.

ترد الواجهة البرمجية على الأخطاء بصيغة RFC 9457، وينسخ العميل حقولها إلى الخطأ:

الحقل النوع محتواه
status number حالة HTTP، أو 0 إذا لم تصل أي استجابة.
code string رمز ثابت تقرؤه البرامج، مثل validation_failed أو verify_resend_limited. يكون http_<status> إذا لم يكن المحتوى JSON، وnetwork_error عندما تكون status صفرًا.
detail string | undefined شرح مقروء للبشر. لا تبن عليه منطقًا، فقد يتغير.
errors Array<{ field, message }> | undefined إدخال لكل حقل غير صالح، في 400 validation_failed وحالات قليلة أخرى.
params Record<string, string | number> | undefined عند الرفض بسبب الباقة: القيم التي يقوم عليها detail، مثل الباقة والحد ووقت التجدد. انظر الرفض بسبب الباقة.
requestId string | undefined معرف الطلب، من المحتوى أو من ترويسة X-Request-Id. اذكره عند التواصل مع الدعم.
headers Headers | undefined ترويسات الاستجابة. تكون undefined في خطأ الشبكة.
retryAfter number | undefined عدد الثواني قبل المحاولة مجددًا، من ترويسة Retry-After (ثوانٍ أو تاريخ) أو من الحقل retryAfter في المحتوى. يضبط في حالات 429 مثل verify_resend_limited وفي بعض حالات 503.
cause unknown في خطأ الشبكة، الخطأ الذي رمته fetch.
message string SMSFabric <status> <code>: <detail>، للسجلات.
handle-errors.ts
import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
try {
await sms.messages.send({ to: '+2010', body: 'Hello' });
} catch (err) {
if (!(err instanceof SMSFabricError)) throw err;
if (err.code === 'validation_failed') {
for (const e of err.errors ?? []) console.error(`${e.field}: ${e.message}`); // to[0]: must be a valid E.164 phone number
} else {
console.error(err.status, err.code, err.detail, err.requestId);
}
}

استخدم retryAfter لتخبر المستخدم متى يستطيع طلب رمز آخر:

retry-after.ts
import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
try {
await sms.verifications.send({ to: '+201001234567' });
} catch (err) {
if (!(err instanceof SMSFabricError) || err.status !== 429) throw err;
const minutes = Math.ceil((err.retryAfter ?? 60) / 60);
console.log(`Too many codes for this number. Try again in ${minutes} min.`); // err.headers.get('retry-after') has the raw value
}

عندما لا يصل أي رد على الطلب (فشل DNS أو رفض الاتصال أو خطأ TLS أو تجاوز timeoutMs)، يحمل الخطأ status: 0 وcode: 'network_error'، ويذكر message السبب الأصلي، مثل Request to SMSFabric failed: fetch failed (connect ECONNREFUSED 127.0.0.1:3000) أو Request to SMSFabric failed: timed out after 30000 ms. والخطأ الأصلي موجود في cause.

القائمة الكاملة، مع ما تفعله لكل رمز، في رموز الأخطاء.

الحالة code ما تفعله
400 validation_failed صحح الحقول المذكورة في errors.
401 unauthorized المفتاح أو الرمز غائب أو خاطئ أو منتهٍ أو مبطل.
403 forbidden المفتاح لا يملك النطاق، أو دور المستخدم لا يملك الصلاحية.
403 api_key_not_allowed نقطة النهاية تحتاج إلى رمز وصول لمستخدم. راجع مفاتيح API.
403 tenant_suspended المؤسسة موقوفة. تواصل مع الدعم.
404 not_found المعرف غير موجود، أو يخص مؤسسة أخرى.
409 idempotency_in_progress طلب بالمفتاح نفسه ما زال قيد التنفيذ. يعيد العميل المحاولة.
409 invalid_campaign_state حالة الحملة لا تسمح بهذا الإجراء. اقرأها أولًا.
422 idempotency_key_reused استخدم المفتاح نفسه مع محتوى مختلف. استخدم مفتاحًا جديدًا.
403 plan_limit_reached وfeature_not_in_plan لا تتسع الباقة لعنصر آخر، أو لا تشمل الميزة. انظر الرفض بسبب الباقة.
429 rate_limited طلبات كثيرة جدًا. ينتظر العميل مدة Retry-After ثم يعيد المحاولة.
429 quota_exceeded استُهلكت حصة الرسائل اليومية أو الشهرية في الباقة. يُرمى الخطأ فورا ولا تعاد المحاولة أبدا.
429 verify_resend_limited وverify_velocity_exceeded حدود خدمة التحقق. لا تعاد محاولتها؛ أخبر المستخدم متى يحاول مجددًا اعتمادًا على retryAfter.
5xx متنوع مشكلة في الخادم. يعيد العميل المحاولة؛ وإذا استمرت، تواصل مع الدعم واذكر requestId.

يعيد العميل بالفعل محاولة 429 و408 و425 و500 و502 و503 و504 و409 idempotency_in_progress وأخطاء الشبكة للطلبات التي يصح تكرارها. الاستثناء هو 429 quota_exceeded: تعود الحصة بنهاية اليوم أو الشهر لا بعد انتظار قصير، فيرمي العميل الخطأ من أول رد. وعندما يرمي الخطأ في النهاية:

  • لا تعد محاولة 400 و401 و403 و404 و422. الطلب نفسه سيفشل بالطريقة نفسها؛ أصلحه أولًا.
  • انتظر تجدد الحصة عند quota_exceeded: احتفظ بالرسائل حتى params.resetsAt.
  • أعد المحاولة لاحقًا عند حالات 429 الأخرى و5xx من طابور مهام له انتظار خاص به، مع الإبقاء على مفتاح منع التكرار نفسه لعمليات الإنشاء.
  • اقرأ الحالة قبل إعادة المحاولة عند network_error في تغيير حالة لا يحمل مفتاح منع تكرار.
retryable.ts
import { SMSFabricError } from '@smsfabric/sdk';
/** True when the same request may succeed later. */
export function isRetryable(err: unknown): boolean {
if (!(err instanceof SMSFabricError)) return false;
if (err.status === 0) return true;
// A used-up plan allowance comes back only when the day or month resets.
if (err.code === 'quota_exceeded') return false;
return err.status === 429 || err.status >= 500;
}

حين يتجاوز طلب حدود باقتك، يحمل الخطأ params بجانب detail المكتوب بالإنجليزية، لتصوغ الرسالة بنفسك أو تتصرف بناء على الأرقام:

code الحالة params
plan_limit_reached 403 plan وresource (phones أو seats أو apiKeys أو webhooks أو recipients) وlimit
feature_not_in_plan 403 plan وfeature (pools أو scheduled_sends أو csv_export)
quota_exceeded 429 plan وperiod (day أو month) وlimit وresetsAt (ISO 8601 بتوقيت UTC)
plan-refusal.ts
import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
try {
await sms.messages.send({ to: '+201001234567', body: 'Your order 1042 has shipped.' });
} catch (err) {
if (!(err instanceof SMSFabricError)) throw err;
const p = err.params ?? {};
if (err.code === 'quota_exceeded') {
console.error(`The ${p['plan']} plan's ${p['period']} allowance of ${p['limit']} is used up until ${p['resetsAt']}.`);
} else if (err.code === 'plan_limit_reached') {
console.error(`The ${p['plan']} plan allows ${p['limit']} ${p['resource']}.`);
} else if (err.code === 'feature_not_in_plan') {
console.error(`The ${p['plan']} plan does not include ${p['feature']}.`);
} else {
throw err;
}
}

تعيد sms.org.plan() الحدود نفسها والاستخدام الذي يقف خلفها (الحساب).

ترميه constructEvent إذا كانت ترويسة SMSFabric-Signature غائبة أو مشوهة، أو كان التوقيع غير مطابق، أو أقدم من الحد المسموح (300 ثانية افتراضيًا)، أو كان المحتوى الموقّع ليس كائن JSON (ويكون SyntaxError في cause). رد بـ 400 ولا تعالج المحتوى. لا تحتاج إلى عميل: استورد constructEvent مباشرة.

signature-error.ts
import { constructEvent, SignatureVerificationError } from '@smsfabric/sdk';
export function parseEvent(rawBody: Buffer, header: string | undefined): { status: number; type?: string } {
try {
const event = constructEvent(rawBody, header, process.env.SMSFABRIC_WEBHOOK_SECRET ?? '');
return { status: 200, type: event.type };
} catch (err) {
if (err instanceof SignatureVerificationError) return { status: 400 };
throw err;
}
}

يرمي new SMSFabric() خطأ Error عاديًا إذا لم يجد بيانات اعتماد: لا apiKey ولا SMSFABRIC_API_KEY ولا accessToken. تحقق من البيئة التي تعمل فيها عمليتك فعلًا.