تتبع كل الأخطاء RFC 7807. جسم الاستجابة بصيغة application/problem+json يحوي الحقول type وtitle وstatus وdetail وrequest_id واختيارياً reason أو errors[].
{
"type": "https://www.kernelhost.com/en/kernelhost-api/errors/payment_required",
"title": "Payment required",
"status": 402,
"detail": "The order could not be paid.",
"request_id": "01HX7Z3K8Q...",
"reason": "insufficient_credit_and_no_card"
}| HTTP | type | المعنى |
|---|---|---|
| 400 | validation_failed | فشل التحقق من المدخلات. راجع errors[] لتفاصيل كل حقل. |
| 401 | auth_failed | فشلت المصادقة. تحتوي الاستجابة دائمًا على reason بقيمة unauthorized (أو ip_not_allowed إذا كان المفتاح مقيدًا بعناوين IP أخرى) ولا تكشف عمدًا أي شيء إضافي. تحقق من المفتاح والـ secret والساعة (±300 ثانية) والـ nonce والتوقيع؛ ويمكن للدعم الفني معرفة السبب الدقيق من خلال request_id. |
| 402 | payment_required | مطلوب الدفع. راجع reason أدناه. |
| 403 | forbidden_scope | الإذن مفقود. reason: missing_scope. |
| 404 | not_found | المورد غير موجود أو غير مرئي لهذا المفتاح (يمنع تعداد المستأجرين). |
| 409 | idempotency_conflict, order_in_progress, service_not_active | تعارض. إما أن قيمة Idempotency-Key استُخدمت من قبل مع جسم مختلف أو على نقطة نهاية أخرى (idempotency_conflict، مع reason بقيمة in_progress ما دام الطلب الأول قيد التنفيذ)، أو أن طلبية أخرى في حسابك لا تزال قيد المعالجة (reason بقيمة order_in_progress، والتزم بترويسة Retry-After)، أو أن الخدمة ليست في حالة تسمح بتنفيذ الإجراء (service_not_active، انظر service_status). |
| 413 | payload_too_large | حجم body الطلب أكبر من 65,536 بايت. يُرفض الطلب قبل المصادقة. |
| 422 | unprocessable | الطلب مفهوم لكن لا يمكن تنفيذه. reason billing_cycle_not_available: المنتج غير متاح في دورة الفوترة هذه. reason zero_total_not_allowed: سيكون الطلب مجانيًا دون سبب صالح مثل رمز ترويجي. |
| 429 | rate_limited | تم تجاوز حد المعدل. التزم بترويسة Retry-After. |
| 500 | internal_error | خطأ داخلي في الخادم. قدّم request_id للربط مع سجل التدقيق عند التواصل مع الدعم. |
أسباب الطلب الدفعي (HTTP 402)
حين يتعذّر دفع الطلبية، تُعيد الواجهة HTTP 402 مع reason قابل للقراءة آلياً في جسم JSON.
insufficient_credit_and_no_card(الرصيد غير كافٍ ولا توجد بطاقة محفوظة. الحل: شحن الرصيد أو إضافة بطاقة في بوابة العملاء.)card_declined(رُفضت البطاقة من قِبل البنك أو البوابة. الحل: تجربة بطاقة أخرى أو التواصل مع البنك.)credit_apply_failed(تعذر تطبيق الرصيد على الفاتورة. لم يُخصم أي مبلغ وأُلغي الطلب. أعد المحاولة باستخدام Idempotency-Key جديد أو تواصل مع الدعم الفني.)client_not_found(معرّف الحساب غير موجود (لا يحدث عملياً تقريباً، تواصل مع الدعم).)
