KWNللمطورينEnglishافتح KWN

المفاهيم

الأخطاء

لكل رفض الشكل نفسه. اعتمد على code، لا على النص.

http
HTTP/1.1 403 Forbidden
{
  "error": "Your access to Sales does not allow that. Ask your company's owner for a higher level.",
  "code": "ROLE_TOO_LOW",
  "app": "sales"
}

error جملة بالإنجليزية للسجلات أو لشخص يقرؤها؛ وcode ثابت وهو ما ينبغي أن تقرأه شيفرتك. وتحمل بعض الرموز حقولًا إضافية — fields عندما لا يجتاز الجسم التحقق، وretryAfter مع 429، وapp عند رفض الصلاحية.

http
HTTP/1.1 400 Bad Request
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID",
  "fields": { "lines": ["At least one line is required."] }
}
الحالةالرموز
400REQUEST_INVALID، RULE_REFUSED، LINES_REQUIRED، CUSTOMER_REQUIRED، PRODUCT_CODE_UNKNOWN، CURSOR_INVALID، EXTERNAL_ID_INVALID، IDEMPOTENCY_KEY_REQUIRED، IDEMPOTENCY_KEY_INVALID، SELLER_TRN_MISMATCH، CUSTOMER_AMBIGUOUS، EINVOICE_TOTAL_MISMATCH، REPORT_PERIOD_INVALID، وقواعد التطبيقات نفسها (NO_CREDITS، CLEARANCE_UNAVAILABLE، EINVOICE_FIELDS_MISSING، PERIOD_LOCKED، …)
401API_KEY_INVALID، MERCHANT_INACTIVE
403APP_LOCKED، APP_NOT_GRANTED، ROLE_TOO_LOW، APPROVAL_REQUIRED
404NOT_FOUND — ومنها سجل شركة أخرى
409EXTERNAL_ID_TAKEN، EXTERNAL_ID_CONFLICT، CONFLICT
422IDEMPOTENCY_KEY_REUSED
429RATE_LIMITED

ما الذي تفعله

  • 400: خطأ في الطلب أو قاعدة عمل. صحّحه قبل الإرسال مجددًا؛ فالطلب نفسه سيُرفض بالطريقة نفسها.
  • 401: المفتاح خاطئ أو ملغى أو الشركة غير نشطة. توقف واطلب من الشركة مفتاحًا صالحًا.
  • 403: لا يحق للمفتاح ذلك. اطلب من الشركة إضافة النطاق، أو إضافة التطبيق إلى الخطة.
  • 409: السجل موجود. اقرأه بـ ?externalId= وتابع منه.
  • 429 و5xx: أعد المحاولة لاحقًا بمفتاح Idempotency-Key نفسه — بعد Retry-After في حالة 429.