جدول الأخطاء
كل خطأ يعود بنفس الشكل، مع error.type ثابت يمكن لنظامك الاعتماد عليه برمجيًا:
{
"error": {
"type": "quota_exceeded",
"message": "رسالة عربية صالحة للعرض للمستخدم النهائي",
"...": "حقول إضافية حسب نوع الخطأ"
}
}
اعتمد على error.type في منطق الكود، واستخدم error.message للعرض فقط —
قد نحسّن صياغة الرسائل دون إشعار، أما الأنواع فمستقرّة داخل الإصدار v1.
401 — المصادقة
type | السبب | الحل |
|---|
missing_api_key | ترويسة Authorization غائبة. | أضف Bearer <KEY>. |
invalid_api_key | المفتاح غير معروف. | تحقّق من النسخ ومن البيئة الصحيحة. |
revoked_api_key | أُبطل المفتاح. | أنشئ مفتاحًا جديدًا. |
expired_api_key | انتهت صلاحيته. | أنشئ مفتاحًا جديدًا. |
account_not_found | الحساب المرتبط محذوف. | تواصل مع الدعم. |
402 — الاشتراك والحصة
type | السبب | حقول إضافية |
|---|
quota_exceeded | نفاد حصة الفواتير الشهرية. | plan, quota, used, period, upgrade_url |
subscription_inactive | الاشتراك متأخّر أو انتهى أمده — الإرسال على البيئة الحقيقية موقوف حتى تأكيد دفع فاتورة الاشتراك. بيئة الاختبار تبقى عاملة. | plan, billing_url, period_end |
403 — الصلاحيات
type | السبب | حقول إضافية |
|---|
insufficient_scope | المفتاح لا يملك الصلاحية. | required_scope, granted_scopes |
plan_limit | الميزة غير متاحة في خطتك (مثل الـ Webhooks). | upgrade_url |
account_suspended | إيقاف إداري للحساب. | — |
404 — غير موجود
type | السبب |
|---|
invoice_not_found | لا فاتورة بهذا المعرّف في حسابك. تذكّر أن الفواتير معزولة بين الوضعين. |
webhook_not_found | نقطة الـ Webhook غير موجودة. |
qr_unavailable | الفاتورة لم تُقبل بعد، فلا رمز QR لها. |
not_found | المسار غير صحيح — راجع العنوان الأساسي /v1/…. |
409 — تعارض
type | السبب | حقول إضافية |
|---|
duplicate_invoice_number | رقم الفاتورة مُستخدم في الوضع نفسه. | existing_invoice_id |
jofotara_credentials_missing | مفتاح live دون ضبط Client-Id/Secret-Key. | invoice_id |
already_accepted | retry على فاتورة مقبولة. | — |
too_many_attempts | تجاوز 10 محاولات إرسال للفاتورة. | — |
already_paid | فاتورة اشتراك مدفوعة مسبقًا. | — |
422 — التحقّق
الحقل error.fields خريطة: مسار الحقل ← قائمة رسائل. مسارات البنود بالشكل lines.0.unit_price.
{
"error": {
"type": "validation_error",
"message": "بيانات الطلب غير صحيحة.",
"fields": {
"invoice_number": ["هذا الحقل مطلوب."],
"customer.name": ["اسم المشتري مطلوب."],
"lines.1.quantity": ["الكمية يجب أن تكون رقمًا أكبر من صفر."],
"lines.2.discount": ["الخصم أكبر من قيمة البند."]
}
}
}
429 — حدّ الطلبات
rate_limited مع ترويسة Retry-After. راجع حدود الاستخدام.
أخطاء البوابة
هذه لا تأتي كرمز HTTP من طرفنا، بل في الحقل data.error مع
status يساوي rejected أو error ورمز 202:
type | المعنى | الإجراء |
|---|
jofotara_rejected | رفضت البوابة المستند؛ الرسالة تحمل تفاصيلها الحرفية. | صحّح البيانات وأصدر فاتورة برقم جديد. |
jofotara_unauthorized | البوابة رفضت Client-Id/Secret-Key. | حدّث بيانات الاعتماد من الإعدادات. |
jofotara_unreachable | انقطاع شبكة أو تعطّل مؤقّت للبوابة. | retry بعد فترة. |
500 / 503
type | الإجراء |
|---|
internal_error | أعد المحاولة بتدرّج أُسّي بنفس Idempotency-Key. إن تكرّر، راسل الدعم بالوقت والمسار. |