الأخطاء
كل استدعاء فاشل للواجهة البرمجية يرمي SMSFabricError بعد أن تنفد محاولات العميل. ويرمي التحقق من خطافات الويب SignatureVerificationError. كلاهما يرث من Error، فيعمل instanceof في ESM وCommonJS.
SMSFabricError
Section titled “SMSFabricError”ترد الواجهة البرمجية على الأخطاء بصيغة 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>، للسجلات. |
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 لتخبر المستخدم متى يستطيع طلب رمز آخر:
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}أخطاء الشبكة
Section titled “أخطاء الشبكة”عندما لا يصل أي رد على الطلب (فشل 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.
الرموز الشائعة
Section titled “الرموز الشائعة”القائمة الكاملة، مع ما تفعله لكل رمز، في رموز الأخطاء.
| الحالة | 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. |
متى تعيد المحاولة
Section titled “متى تعيد المحاولة”يعيد العميل بالفعل محاولة 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في تغيير حالة لا يحمل مفتاح منع تكرار.
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;}الرفض بسبب الباقة
Section titled “الرفض بسبب الباقة”حين يتجاوز طلب حدود باقتك، يحمل الخطأ 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) |
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() الحدود نفسها والاستخدام الذي يقف خلفها (الحساب).
SignatureVerificationError
Section titled “SignatureVerificationError”ترميه constructEvent إذا كانت ترويسة SMSFabric-Signature غائبة أو مشوهة، أو كان التوقيع غير مطابق، أو أقدم من الحد المسموح (300 ثانية افتراضيًا)، أو كان المحتوى الموقّع ليس كائن JSON (ويكون SyntaxError في cause). رد بـ 400 ولا تعالج المحتوى. لا تحتاج إلى عميل: استورد constructEvent مباشرة.
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; }}أخطاء الإعداد
Section titled “أخطاء الإعداد”يرمي new SMSFabric() خطأ Error عاديًا إذا لم يجد بيانات اعتماد: لا apiKey ولا SMSFABRIC_API_KEY ولا accessToken. تحقق من البيئة التي تعمل فيها عمليتك فعلًا.