الانتقال إلى المحتوى الرئيسي
عرض بصيغة Markdownفتح في Claudeفتح في ChatGPT

أكواد الأخطاء

جميع الأخطاء ترجع بالشكل نفسه. اعتمد على code في الكود عندك، أما message فهي نص موجّه للمستخدم وتتغيّر لغتها حسب الـ Header Accept-Language.

{
  "error": {
    "type": "invalid_request_error",
    "code": "phone_taken",
    "message": "رقم الجوال مسجّل لعميل آخر.",
    "param": "phone",
    "docUrl": "https://docs.kosoor.com.sa/ar/errors#phone_taken",
    "existingId": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}
الحقلالوصف
typeتصنيف الخطأ، وهو أحد العناوين في هذه الصفحة.
codeكود الخطأ، ولا يتغيّر بين الإصدارات.
messageوصف الخطأ بلغة الطلب.
paramالحقل أو الـ Query Parameter أو الـ Header الذي سبّب الخطأ، بمسار مثل company.vatNumber. قيمته null إذا لم يكن الخطأ متعلقاً بحقل معيّن.
docUrlرابط شرح الكود في هذه الصفحة.
errorsفي أخطاء 400: قائمة بكل مشاكل الطلب، بما فيها المشكلة الأولى.
requiredPermissionمع missing_permission: الصلاحية التي يحتاجها الطلب، مثل customers:write.
existingIdمع الأكواد التي تنتهي بـ _taken: الـ id للسجل الذي يستخدم القيمة نفسها، إذا كان من نوع المورد نفسه ويملك مفتاحك صلاحية قراءته.
missingمع customer_address_incomplete: حقول العميل الناقصة لإصدار فاتورة ضريبية، مثل address.street.
zatcaErrorsمع zatca_rejected: رسائل الهيئة كما أرسلتها، ولكل رسالة code و category و message.

المصادقة​

missing_api_key​

HTTP Status: 401

لم يتم إرسال مفتاح API. أرسله في الـ Header بالشكل: Authorization: Bearer <key>.

invalid_api_key​

HTTP Status: 401

مفتاح API غير صحيح.

revoked_api_key​

HTTP Status: 401

تم إلغاء مفتاح API هذا.

expired_api_key​

HTTP Status: 401

انتهت صلاحية مفتاح API هذا.

الصلاحيات​

tenant_suspended​

HTTP Status: 403

حساب المنشأة موقوف.

missing_permission​

HTTP Status: 403

مفتاح API لا يملك الصلاحية المطلوبة لهذا الطلب.

branch_not_allowed​

HTTP Status: 403

مفتاح API غير مسموح له بالعمل على هذا الفرع.

أخطاء في الطلب​

invalid_json​

HTTP Status: 400

الـ Body ليس JSON صحيحاً.

missing_parameter​

HTTP Status: 400

أحد الحقول المطلوبة غير موجود.

invalid_parameter​

HTTP Status: 400

قيمة أحد الحقول غير صحيحة.

unknown_parameter​

HTTP Status: 400

الطلب يحتوي على حقل لا يقبله هذا الـ Endpoint.

too_many_errors​

HTTP Status: 400

في الطلب أخطاء أخرى غير المذكورة هنا.

unsupported_media_type​

HTTP Status: 415

أرسل الـ Body بصيغة application/json.

body_too_large​

HTTP Status: 413

حجم الـ Body أكبر من الحد المسموح.

route_not_found​

HTTP Status: 404

لا يوجد Endpoint بهذا الرابط.

method_not_allowed​

HTTP Status: 405

هذا الـ Endpoint لا يقبل الـ HTTP Method المستخدم.

resource_not_found​

HTTP Status: 404

السجل المطلوب في الرابط غير موجود.

reference_id_taken​

HTTP Status: 409

قيمة referenceId مستخدمة لسجل آخر.

invoice_not_cleared​

HTTP Status: 409

لم تقبل هيئة الزكاة والضريبة والجمارك هذه الفاتورة. راجع قيمة zatca.status.

invoice_busy​

HTTP Status: 409

هناك طلب آخر يعدّل هذه الفاتورة الآن. أعد المحاولة بعد ثوانٍ.

invalid_vat_number​

HTTP Status: 400

الرقم الضريبي يتكون من 15 رقماً، يبدأ بـ 3 وينتهي بـ 3.

vat_number_taken​

HTTP Status: 409

الرقم الضريبي مسجّل لعميل آخر.

phone_taken​

HTTP Status: 409

رقم الجوال مسجّل لعميل آخر.

قواعد العمل​

referenced_resource_not_found​

HTTP Status: 422

الطلب يشير إلى سجل غير موجود.

invoice_not_issued​

HTTP Status: 422

لم يتم إصدار الفاتورة.

on_account_not_allowed​

HTTP Status: 422

العميل الفرد لا يشتري بالآجل.

credit_limit_exceeded​

HTTP Status: 422

تجاوز الحد الائتماني.

customer_inactive​

HTTP Status: 422

العميل غير نشط.

customer_address_incomplete​

HTTP Status: 422

الفاتورة الضريبية تحتاج عنوان العميل (الشركة) كاملاً مع الرقم الضريبي أو رقم الهوية. الحقول الناقصة موضحة في missing.

item_not_sellable​

HTTP Status: 422

لا يمكن بيع هذا المنتج في فاتورة مبيعات.

branch_not_onboarded​

HTTP Status: 422

هذا الفرع غير مربوط بهيئة الزكاة والضريبة والجمارك، فلا يمكنه إصدار فاتورة ضريبية.

zatca_rejected​

HTTP Status: 422

رفضت هيئة الزكاة والضريبة والجمارك الفاتورة، ولم يُحفظ أي شيء. رسائل الهيئة موضحة في zatcaErrors.

allocation_exceeds_due​

HTTP Status: 422

المبلغ المخصص أكبر من المتبقي على هذه الفاتورة.

invoice_not_payable​

HTTP Status: 422

لا يمكن سداد هذه الفاتورة، لأنها غير موجودة، أو لعميل آخر، أو في فرع لا يملك المفتاح صلاحية عليه، أو غير صادرة، أو ليست فاتورة مبيعات.

period_locked​

HTTP Status: 422

هذا التاريخ في فترة محاسبية مقفلة.

payment_method_not_in_branch​

HTTP Status: 422

خزينة طريقة الدفع هذه تخدم فرعاً آخر، فلا يمكن تسجيل الدفعة في الفرع المحدد.

payment_not_recorded​

HTTP Status: 422

لم يتم تسجيل الدفعة.

webhook_endpoint_limit​

HTTP Status: 422

وصل هذا المفتاح إلى الحد الأقصى لعدد الـ Webhook Endpoints، احذف واحداً لا تستخدمه أولاً.

credit_exceeds_invoice​

HTTP Status: 422

مبلغ الإشعار أكبر من المتبقي القابل للإشعار على الفاتورة.

invoice_not_creditable​

HTTP Status: 422

لا يمكن إصدار إشعار دائن لهذه الفاتورة، لأنها ليست فاتورة مبيعات صادرة، أو مستوردة، أو رفضتها الهيئة.

used_subscription_not_refundable​

HTTP Status: 422

هذا الاشتراك استُخدمت منه زيارات، فلا يمكن إصدار إشعار دائن له عن طريق الـ API.

refund_exceeds_collected​

HTTP Status: 422

مبلغ الاسترجاع أكبر مما حُصّل على الفاتورة.

refund_method_not_supported​

HTTP Status: 422

دُفعت هذه الفاتورة ببطاقة عبر المتجر الإلكتروني، ولا يمكن بدء استرجاع إلى البطاقة عن طريق الـ API.

loyalty_refund_blocked​

HTTP Status: 422

تعذّر إصدار هذا الإشعار بسبب منصة الولاء: إما أن النقاط أو الأختام المكتسبة من هذه الفاتورة استُخدمت، أو تعذّر الوصول إلى المنصة، أو لم تصلها الفاتورة بعد.

credit_note_not_issued​

HTTP Status: 422

لم يتم إصدار الإشعار الدائن.

منع تكرار الطلبات​

missing_idempotency_key​

HTTP Status: 400

أرسل الـ Header Idempotency-Key مع هذا الطلب.

invalid_idempotency_key​

HTTP Status: 400

قيمة الـ Header Idempotency-Key غير صحيحة.

idempotency_key_reused​

HTTP Status: 422

قيمة Idempotency-Key هذه استُخدمت من قبل مع طلب مختلف.

idempotency_in_progress​

HTTP Status: 409

يوجد طلب بنفس قيمة Idempotency-Key لم ينتهِ تنفيذه بعد.

تجاوز حد الطلبات​

rate_limited​

HTTP Status: 429

تجاوزت الحد المسموح من الطلبات. أعد المحاولة بعد المدة الموضحة في Retry-After.

أخطاء السيرفر​

internal_error​

HTTP Status: 500

حدث خطأ من جهتنا. أعد المحاولة، وإذا تكرر الخطأ أرسل لنا قيمة Request-Id.

sandbox_unavailable​

HTTP Status: 503

بيئة الاختبار قيد التجهيز. أعد المحاولة بعد قليل.

sandbox_failed​

HTTP Status: 503

تعذّر تجهيز بيئة الاختبار، ولن تنجح إعادة المحاولة حتى يُعيد التاجر تعيينها من صفحة المطوّرين في لوحة التحكم.