الأخطاء
الطلب المرفوض يُجاب بحالة HTTP ومشكلة بصيغة RFC 9457 (Content-Type: application/problem+json). تفرّع على
الحالة أولًا ثم على code. لا تحلّل title ولا detail: هما للبشر.
من الخدمة
تأتي أغلب الأخطاء من الخدمة التي خلف العملية:
{
"type": "https://errors.zaitrack.app/ZTK74001",
"title": "Not Found",
"status": 404,
"code": "ZTK74001",
"detail": "not found"
}
codeهوZTKوأرقام. لكل خدمة نطاق خاص بها، ويحتفظ الرمز بمعناه بعد نشره.detailيذكر الخطأ، مثلvehicleId (required) and driverId must be UUIDs. بعض الخدمات تضع الرسالة فيtitleولا ترسلdetail.
| الحالة | معناها |
|---|---|
400 | الجسم أو أحد المعاملات غير صالح: صحّح الطلب. |
401 | لم تمرّر البوابة إلى الخدمة أي مؤسسة (خلل في البوابة أو الإعداد: أبلغ عنه). |
404 | لا يوجد هذا المورد في مؤسستك. ومورد مؤسسة أخرى 404 أيضًا. |
409 | حالة المورد تمنع الإجراء (جهاز مرتبط من قبل، مهمة موزّعة من قبل). |
412 | يذكر If-Match إصدارًا لم يعد الحالي: اقرأ مجددًا. |
422 | يذكر الجسم شيئًا غير موجود أو ليس لك (معرّف جهاز أو سائق). |
500 | خلل من جهتنا: أعد المحاولة لاحقًا وأبلغ عن X-Zaitrack-Request-Id. |
من البوابة
تجيب البوابة قبل الخدمة حين يكون الخطأ في بيانات الاعتماد أو النطاق أو مفتاح منع التكرار أو المنطقة. مشكلاتها
لها type تحت https://api.zaitrack.app/errors/ وcode منقوط وrequest_id:
{
"type": "https://api.zaitrack.app/errors/scope-missing",
"title": "Required scope missing",
"status": 403,
"code": "auth.token.scope_missing",
"detail": "Missing scopes: vehicles:write",
"request_id": "…"
}
| الحالة | code | معناها |
|---|---|---|
401 | auth.api_key.invalid | المفتاح مشوّه أو مجهول أو مُبطل أو منتهٍ. |
403 | auth.api_key.ip_not_allowed | للمفتاح قائمة عناوين مسموح بها وعنوانك ليس فيها. |
403 | auth.tenant_missing | بيانات الاعتماد غير مرتبطة بمؤسسة. |
403 | auth.token.scope_missing | ينقص بيانات الاعتماد نطاق العملية؛ ويذكره detail. |
403 | step_up_required | تحتاج العملية إلى تحقق MFA حديث (أوامر الأجهزة). |
400 | idempotency.required | تحتاج العملية إلى Idempotency-Key. |
409 | idempotency.body_mismatch | استُخدم المفتاح من قبل بجسم مختلف. |
409 | idempotency.in_flight | طلب بهذا المفتاح ما زال قيد التنفيذ. |
421 | misdirected_request | مؤسستك في منطقة أخرى: اتبع Location. راجع المناطق. |
503 | auth.api_key.unavailable، idempotency.unavailable | إحدى تبعيات البوابة متوقفة: أعد المحاولة بتأخير متزايد. |
ردّان ليسا مشكلات:
- رمز وصول OAuth غير صالح أو منتهٍ يتلقى
401مع ترويسةWWW-Authenticate: Bearer. - الطلب الذي يتجاوز حدّ المعدّل يتلقى
429مع{"error_msg": "rate limit exceeded"}. راجع حدود المعدّل.