الأخطاء
كل خطأ كائن JSON برمز ثابت ورسالة وrequest_id. القائمة الكاملة للرموز وسبب كل منها وهل تُعاد المحاولة.
كل خطأ هو كائن JSON واحد يحوي code ثابتًا تبني عليه المنطق، وmessage مقروءة، وrequest_id تذكره للدعم. أصلح أخطاء 4xx وأعد الإرسال؛ ولا تعد المحاولة إلا مع 429 بعد Retry-After ومع 5xx بتراجع تدريجي.
شكل الخطأ
كل استجابة خطأ هي JSON بكائن error واحد:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Validation failed",
"request_id": "8f3c2a1e-4b6d-4e7f-9a0b-1c2d3e4f5a6b",
"fields": {
"to": "range exceeds 31 days"
}
}
}| الحقل | الوصف |
|---|---|
code | رمز ثابت مقروء آليًا. ابنِ المنطق عليه لا على message. |
message | ملخص مقروء للبشر. قد يتغير؛ لا تحلّله. |
request_id | معرّف الطلب. أرفقه عند التواصل مع دعم أوكتين. |
fields | فقط مع VALIDATION_FAILED: خريطة من اسم المعامل إلى المشكلة. |
الاستجابات المنتَجة على الحافة (IP_NOT_ALLOWED، RATE_LIMITED) تحوي code فقط.
رموز الأخطاء
| الحالة | الرمز | المعنى | ما ينبغي فعله |
|---|---|---|---|
400 | VALIDATION_FAILED | معامل مفقود أو غير صالح أو خارج النطاق. | اقرأ fields وأصلح الطلب. لا تعد المحاولة دون تغيير. |
401 | INVALID_API_KEY | المفتاح مفقود أو غير معروف أو معطّل. | تحقق من ترويسة X-API-Key. إذا عُطّل المفتاح، احصل على مفتاح جديد من أوكتين. لا تعد المحاولة دون تغيير. |
403 | IP_NOT_ALLOWED | عنوان IP المصدر ليس في قائمة المفتاح. | أرسل العنوان إلى أوكتين لإضافته. لا تعد المحاولة حتى يُضاف. |
403 | API_INTEGRATION_NOT_ENABLED | تكامل الواجهة معطّل على حسابك. | تواصل مع مدير حسابك في أوكتين. |
403 | NO_ACTIVE_CHARGING_PROFILE | ليس لحسابك ملف تسعير نشط وغير منتهٍ. | تواصل مع مدير حسابك في أوكتين للتجديد. |
403 | EDGE_NOT_ENFORCED | مشكلة إعداد من جانب أوكتين. | تواصل مع دعم أوكتين مع request_id. |
404 | CORPORATE_NOT_FOUND | قيمة corporate_id ليست ضمن حسابك. | تحقق من المعرّف. |
404 | CORPORATE_GROUP_NOT_FOUND | قيمة corporate_group_id ليست ضمن حسابك. | تحقق من المعرّف. |
429 | RATE_LIMITED | أكثر من 60 طلبًا في الدقيقة الحالية. | انتظر Retry-After ثانية وأعد المحاولة. راجع حد المعدل. |
5xx | خطأ مؤقت في الخادم. | أعد المحاولة بتراجع أسّي. |
أي الأخطاء أعيد محاولتها؟
| الحالة | إعادة المحاولة؟ |
|---|---|
400، 401، 403، 404 | لا. أصلح السبب أولًا. |
429 | نعم، بعد Retry-After ثانية. |
5xx، انتهاء مهلة الشبكة | نعم، بتراجع أسّي وحد أقصى (مثلًا 5 محاولات تبدأ من ثانيتين). |
عادةً ما تشير أخطاء التحقق في نقطة نهاية المعاملات إلى إحدى هذه المشكلات في fields:
| المعامل | المشكلات الشائعة |
|---|---|
from، to | مفقود، أو ليس ISO 8601، أو to قبل from، أو النطاق يتجاوز 31 يومًا |
limit | ليس عددًا صحيحًا، أو أقل من 1، أو أكبر من 100 |
status | قيمة غير CONFIRMED أو EXTERNAL |
corporate_id | ليس عددًا صحيحًا أو قائمة أعداد صحيحة مفصولة بفواصل |
cursor | غير صالح |
ترقيم الصفحات
تُرقَّم نقطة نهاية المعاملات بمؤشر معتم. مرر next_cursor مع المرشحات نفسها حتى تصبح has_more خاطئة. لا سجلات متخطاة ولا مكررة.
نظرة عامة على الويب هوك
ترسل أوكتين طلب POST موقّعًا عبر HTTPS إلى نقطة النهاية لديك عند تأكيد معاملة أو تسجيل معاملة خارجية. متطلبات نقطة النهاية وأنواع الأحداث.