المرجع / رموز الأخطاء
رموز الأخطاء
كل خطأ JSON يحمل message. أخطاء التحقق تضيف كائن errors مفهرساً بالحقل. حالة HTTP تخبرك إن كان عليك إصلاح الطلب أو الانتظار أو مراجعة لوحة التحكم.
حُدّث في 21 أكتوبر 2026
عدّل هذه الصفحة
01الصيغة
تستخدم الأخطاء حالات HTTP المتعارف عليها ورسالة إنجليزية قصيرة. أرسل Accept: application/json لتضمن ألا تعود إليك صفحة HTML أبداً.
HTTP/1.1 422 Unprocessable Content
{ "message": "Call is full" }
HTTP/1.1 422 Unprocessable Content
{
"message": "The user ref field is required. (and 1 more error)",
"errors": {
"user_ref": ["The user ref field is required."],
"display_name": ["The display name field is required."]
}
}
02حالات HTTP
كل خطأ يعيده الـ API.
| الحالة | الرسالة | المعنى |
|---|---|---|
401
|
Invalid API key
|
لا bearer token، أو مفتاح غير موجود. تحقق من البيئة: المفتاح الفعلي لا يرى المكالمات التجريبية. |
403
|
App is inactive
|
عُطّل التطبيق أو حُذف في لوحة التحكم. |
403
|
Organization is suspended
|
المؤسسة موقوفة. تواصل مع الدعم. |
403
|
Live mode is not enabled for this app
|
استُخدم مفتاح فعلي قبل تفعيل الوضع الفعلي للتطبيق. |
404
|
Call not found
|
معرّف مجهول، أو مكالمة تطبيق أو بيئة أخرى. |
404
|
Not Found
|
مسار خاطئ. كل شيء تحت /api/v1/calls.
|
422
|
The … field is required.
|
حقل ناقص أو غير صالح؛ راجع errors.
|
422
|
Call is full
|
في المكالمة فعلاً مشاركان (فردية) أو عشرة (جماعية) نشطون. |
422
|
Call is not live
|
المكالمة منتهية أو فائتة أو مرفوضة أو فاشلة؛ لا تقبل رموزاً ولا يمكن إنهاؤها. |
429
|
Too Many Attempts.
|
أكثر من 120 طلباً في الدقيقة لهذا المفتاح. انتظر Retry-After ثانية.
|
500
|
Server Error
|
خلل من جهتنا. آمن أن تعيد المحاولة؛ أخبرنا إن استمر. |
03قواعد التحقق
ما يقبله كل حقل. أخطاء التحقق تعود 422 برسالة لكل حقل.
| الحقل | القاعدة |
|---|---|
type
|
one_to_one | group
|
ring
|
true | false
|
region
|
auto | baghdad | dubai | istanbul
|
metadata
|
object, ≤ 20 keys
|
user_ref
|
required, ≤ 120 chars
|
display_name
|
required, ≤ 80 chars
|
ttl
|
60 – 3600 seconds
|
status
|
ringing | in_progress | completed | missed | declined | failed
|
per_page
|
1 – 100
|
04في حزم SDK
حزمة Laravel ترمي ApiException بالحالة والرسالة والأخطاء نفسها. وفي المتصفح، يطلق SDK الويب error للمشاكل القابلة للتعافي وended بسبب error حين يتعذّر استمرار المكالمة.
app/Http/Controllers/CallController.php
1
use Sada\Laravel\Exceptions\ApiException;
2
3
try {
4
$token = $call->token($userRef);
5
} catch (ApiException $e) {
6
$e->status; // 422
7
$e->getMessage(); // "Call is full"
8
$e->errors; // validation errors keyed by field, or []
9
}
05أخطاء الـ webhooks
الميدل وير sada.webhook يردّ بـ 401 على التوقيع الناقص أو المشوّه أو الخاطئ أو القديم. ومسارك أنت ينبغي أن يردّ بـ 2xx على الأحداث التي لا تهمه بدل 4xx — فالـ 4xx يُعاد كأي فشل.
هل كانت هذه الصفحة مفيدة؟
✓ شكراً، وصلتنا ملاحظتك.