شكل الاستجابة: { "error": "code", "message": "…", "error_code": "SH_xxx", "doc_url": "…", "request_id": "…" }. أخطاء التحقق من المدخلات تستخدم validation_error (400).
error_code ثابت (SH_xxx)
| SH | Legacy | HTTP | المعنى |
|---|
| SH_001 | unauthorized … | 401 | مصادقة غير صالحة |
| SH_013 | test_mode_only | 403 | يتطلب مفاتيح test |
| SH_014 | receipt_already_used | 409 | إعادة استخدام receipt |
| SH_015 | idempotency_conflict | 409 | تعارض Idempotency-Key |
أخطاء العميل (4xx)
| HTTP | Code | الوصف |
|---|
| 400 | invalid_phone | رقم الهاتف غير صالح أو لم يمر بالتطبيع |
| 400 | invalid_state | حالة الجلسة لا تسمح بهذا الإجراء |
| 400 | invalid_range | نطاق التحليلات غير صالح (0–90 يوماً) |
| 400 | invalid_organization | معرف المنظمة غير صالح |
| 400 | invalid_invitation | الدعوة منتهية أو غير صالحة |
| 400 | owner_protected | لا يمكن تعديل أو إزالة مالك المنظمة |
| 400 | invalid_request | طلب فوترة غير صالح |
| 400 | invalid_webhook_url | عنوان Webhook غير صالح |
| 400 | webhook_https_required | يجب أن يستخدم Webhook HTTPS |
| 400 | webhook_private_address | العنوان يشير إلى شبكة خاصة أو محجوزة |
| 400 | validation_error | فشل التحقق من بنية الطلب |
| 401 | unauthorized | رمز أو مفتاح مصادقة مفقود أو غير صالح |
| 401 | invalid_credentials | بريد إلكتروني أو كلمة مرور غير صحيحة |
| 401 | invalid_refresh | رمز التحديث غير صالح أو مستخدم مسبقاً |
| 402 | plan_expired | انتهت صلاحية خطة التطبيق |
| 402 | insufficient_credits | لا يوجد رصيد كافٍ للتحقق |
| 403 | account_inactive | حساب المطور غير نشط |
| 403 | forbidden | صلاحيات غير كافية |
| 403 | app_disabled | التطبيق معطّل |
| 403 | app_frozen | التطبيق مجمد إدارياً |
| 403 | package_mismatch | اسم الحزمة لا يطابق التطبيق المسجل |
| 403 | signature_not_registered | بصمة SHA256 غير مسجلة |
| 403 | test_mode_only | مفتاح live حيث تُطلَب مفاتيح test (SH_013) |
| 404 | not_found | المورد غير موجود |
| 404 | organization_not_found | لا توجد منظمة نشطة للمستخدم |
| 409 | email_exists | البريد الإلكتروني مسجل مسبقاً |
| 409 | member_exists | المستخدم عضو في المنظمة بالفعل |
| 409 | gateway_number_mismatch | رقم البوابة في heartbeat لا يطابق المسجل |
| 409 | last_admin | لا يمكن تغيير آخر مسؤول للمنصة |
| 409 | self_protected | لا يمكن إزالة صلاحياتك الإدارية |
| 409 | receipt_already_used | Receipt مستخدم مسبقاً |
| 409 | idempotency_conflict | تعارض Idempotency-Key |
| 401 | receipt_invalid | Receipt JWT غير صالح |
| 422 | webhook_redirect | عنوان Webhook أعاد توجيهاً (غير مسموح) |
| 422 | webhook_rejected | نقطة Webhook رفضت الطلب |
| 422 | webhook_dns_failed | فشل DNS لاسم المضيف |
| 422 | webhook_connection_failed | تعذر الاتصال بعنوان Webhook |
| 429 | concurrent_limit_exceeded | عدد جلسات الانتظار تجاوز الحد |
أخطاء الخادم (5xx)
| HTTP | Code | الوصف |
|---|
| 502 | email_delivery_failed | تعذر إرسال بريد الدعوة |
| 503 | gateway_unavailable | لا توجد بوابة متصلة للتحقق |
| 503 | email_not_configured | خدمة البريد غير مهيأة |
| 504 | webhook_timeout | انتهت مهلة اختبار Webhook (10 ث) |
| 500 | internal_error | خطأ داخلي غير متوقع |
أرفق request_id عند التواصل مع الدعم — يظهر في سجلات API.
