الأخطاء

أشكال الأخطاء

هناك ثلاثة أشكال. اقرأ الحالة أولاً ثم الجسم. 1. detail نص (معظم الأخطاء).

{ "detail": "Invalid or revoked API key" }

2. detail كائن يحمل code ثابتاً (اعتمد على code وليس على الرسالة).

{
  "detail": {
    "code": "kyc_extract_cap_reached",
    "message": "Monthly document-read limit of 2000 reached.",
    "used": 2000,
    "limit": 2000
  }
}

3. code وmessage في المستوى الأعلى، دون detail. تأتي هذه من محدد المعدل، ومعالج المسار غير المعروف، والمعالج الشامل للأخطاء غير المتوقعة.

{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down." }

يحمل خطأ المخطط 422 قائمة في detail، بإدخال واحد لكل حقل غير صالح:

{
  "detail": [
    { "type": "string_pattern_mismatch", "loc": ["body", "reference"], "msg": "String should match pattern '^[A-Za-z0-9_.:-]+$'", "input": "client 1", "ctx": { "pattern": "^[A-Za-z0-9_.:-]+$" } }
  ]
}

يحدد loc موضع الخطأ: ["body", "reference"] لجسم JSON، و["query", "environment"] أو ["path", "key"]. وفي حقل نموذج multipart يكون العنصر الأول هو body أيضاً. تعامل مع الأشكال الثلاثة جميعاً: العميل الذي يفترض أن detail كائن دائماً سيفشل عند أول خطأ 422.

معرّف الطلب

تحمل كل استجابة الترويسة X-Request-ID. إذا أرسلت معرّفك الخاص (من 1 إلى 64 حرفاً من A-Z a-z 0-9 . _ : -) أعادته Sahl، وإلا أنشأت معرّفاً. تُدرج كل مكالمة بمفتاح في Developers, Call log في وحدة التحكم تحت هذا المعرّف. اذكره عند مراسلة Sahl.

الفهرس

400 طلب غير صالح

الرسالة	السبب	الحل
`Send between 1 and 5 files.`	لم يتلقَّ `/extract` أي ملف أو تلقى أكثر من 5.	أرسل من 1 إلى 5 أجزاء `files`.
`Unsupported file type '<mime>'. Allowed types: application/pdf, image/jpeg, image/png, image/tiff, image/webp`	`Content-Type` الخاص بالجزء ليس من الأنواع الخمسة. يُقبل `image/jpg` على أنه JPEG.	حوّل الملف أو اضبط نوع المحتوى الصحيح على الجزء.
`File content does not match declared MIME type.`	البايتات الأولى لا تطابق نوع المحتوى الذي صرحت به (ملف PNG أُرسل على أنه `application/pdf`، أو ملف ليس صورة ولا PDF).	أرسل الملف الحقيقي بنوعه الحقيقي. يجوز أن يسبق `%PDF-` ما يصل إلى 1 KB في ملف PDF.

401 غير مصرح

الرسالة	السبب	الحل
`Missing API key`	لا توجد ترويسة `Authorization: Bearer ...`.	أرسلها.
`Invalid or revoked API key`	مفتاح خاطئ أو مشوه أو ملغى.	تحقق من المفتاح. أنشئ مفتاحاً جديداً إذا أُلغي.
`API key expired`	مفتاح جرى تدويره وانتهت فترة السماح الخاصة به.	استخدم المفتاح الجديد.
`Partner identity could not be verified`	المفتاح مرتبط بحساب خدمة و`X-Partner-Identity` مفقودة أو خاطئة.	أرسل رمز هوية Google صالحاً للحساب المرتبط، مع الجمهور (audience) الوارد في نموذج المفتاح.

403 محظور

الجسم	السبب	الحل
`"API key lacks the kyc:verify scope"` (نص، ويتغير اسم النطاق)	لا يملك المفتاح النطاق المطلوب لنقطة النهاية.	أنشئ مفتاحاً بهذا النطاق. راجع النطاقات.
`{"code": "kyc_scope_not_allowed", "message": "This workspace is not enabled for the partner KYC API."}`	يحمل المفتاح نطاق `kyc:` لكن مساحة العمل غير مفعّلة. الوصول إلى Partner API يتم لكل مساحة عمل.	اطلب الوصول إلى sandbox.
`{"code": "direct_access_refused", "message": "Call the API at https://app.sahlfinancial.com/api."}`	استدعيت العنوان الداخلي لـ Sahl.	استخدم المضيف العام.

404 غير موجود

الجسم	السبب	الحل
`{"detail": "identity verification is not set up for this tenant"}`	نقطة نهاية eID في مساحة عمل لا تملك حساب مزود eID.	تواصل مع Sahl لإعداد eID.
`{"detail": "Not Found"}`	`GET /v1/kyc/eid/{key}` أو تقريره: المفتاح غير موجود أو يخص مساحة عمل أخرى.	استخدم `key` الذي أعاده `POST /v1/kyc/eid`.
`{"code": "not_found", "message": "API endpoint not found: GET /api/..."}`	المسار أو الطريقة غير موجودة.	تحقق من المسار. ينتهي عنوان base URL بـ `/api`.

413 الحمولة كبيرة جداً

الرسالة	السبب	الحل
`File too large. Maximum allowed size is 30 MB.`	ملف يتجاوز الحد (30 MB افتراضياً).	اضغطه أو قسّمه.
`Image is 9000x9000 pixels; the maximum is 50 megapixels.`	ترويسة الصورة تعلن أكثر من 50 ميغابكسل. قد يُرفض ملف صغير الحجم مع ذلك.	قلّل الأبعاد.
`Image dimensions are too large to process.`	رصدت Pillow قنبلة فك ضغط.	أرسل صورة عادية.

422 تعذّرت المعالجة

الرسالة	السبب	الحل
`reference must be 1-64 characters of A-Z a-z 0-9 _ . : -`	حقل نموذج في `/extract`.	استخدم هذه الأحرف فقط.
`environment must be 'sandbox' or 'production'`	حقل نموذج في `/extract`.	استخدم إحدى القيمتين.
`subject must be at most 255 characters`	حقل نموذج في `/extract`.	اختصره.
`identity verification is available for Canadian clients only`	`/v1/kyc/eid` مع `country` ليس `CA` ولا `CAN`.	eID مخصص للعملاء الكنديين.
قائمة من `{type, loc, msg}`	حقل في JSON أو الاستعلام أو المسار يخالف المخطط: `reference` أو `environment` غير صالح، أو `email` ليس بريداً إلكترونياً، أو `documents` ليس 1 أو 2، أو `key` ليس عدداً صحيحاً، أو حقل مطلوب مفقود.	اقرأ `loc` و`msg`.

قيمة kind الخاطئة ليست خطأً: تُعامل القيم غير المعروفة على أنها individual.

429 طلبات كثيرة جداً

الجسم	السبب	الحل
`{"detail": {"code": "kyc_extract_cap_reached", "message": "Monthly document-read limit of 2000 reached.", "used": 2000, "limit": 2000}}`	استنفدت مساحة العمل عمليات القراءة المتاحة للشهر التقويمي (UTC). تُحتسب قبل تشغيل النموذج، فالمكالمة المرفوضة لا تستهلك شيئاً.	انتظر الشهر التالي أو اطلب من Sahl رفع الحد. لا تعد المحاولة.
`{"code": "rate_limit_exceeded", "message": "Too many requests. Please slow down."}`	أكثر من 100 طلب في الدقيقة من عنوان IP واحد للعميل على هذه المسارات. الترويسات: `Retry-After` (بالثواني)، `X-RateLimit-Limit`، `X-RateLimit-Remaining`.	انتظر `Retry-After` ثانية.

تحمل كل استجابة ناجحة أيضاً X-RateLimit-Limit وX-RateLimit-Remaining. الحد يُطبق لكل عنوان IP للعميل وليس لكل مفتاح، لذا تتشاركه عدة خوادم خلف عنوان واحد. القيمة 100 في الدقيقة هي الافتراضية في الشيفرة وقد تتغير.

500 و502

الحالة	الجسم	السبب	الحل
500	`{"code": "internal_error", "message": "An unexpected error occurred", "details": null}`	عطل غير متوقع من جانب Sahl.	أعد المحاولة مرة واحدة. إذا استمر، اذكر `X-Request-ID`.
502	`{"detail": "the identity verification service did not answer"}`	لم يستجب مزود eID.	أعد المحاولة لاحقاً.

تعذّر الوصول إلى القارئ ليس خطأً: يرد /extract بالحالة 200 مع reader_unavailable: true. راجع قراءة المستندات.

إعادة المحاولة

لا يوفر API مفتاح idempotency. فكّر في كل مكالمة قبل إعادتها.

المكالمة	هل إعادتها آمنة؟	ماذا تفعل الإعادة
`GET /v1/kyc/eid/{key}` و`/report`	نعم	تقرأ من جديد.
`POST /v1/kyc/verify`, `POST /v1/kyc/assess`	نعم فعلياً	الحكم دالة خالصة لمحتوى الطلب. الإعادة مع `reference` تحفظ الحكم في الحالة مرة أخرى وترسل webhook مرة أخرى. أزل التكرار بالاعتماد على `event_id`.
`POST /v1/kyc/extract`	فقط بعد فشل في الشبكة أو 5xx	تقرأ من جديد وتحتسب من جديد. ومع `reference` تحفظ المستندات مرة أخرى، فتحتوي الحالة حينئذ على نسختين.
`POST /v1/kyc/eid`	تجنّبها	تراسل العميل بالبريد مرة أخرى وتستبدل الطلب المسجل في الحالة.

قواعد عملية:

لا تعد محاولة أي 4xx، باستثناء 429 الخاص بـ rate_limit_exceeded الذي يحمل Retry-After. فأي 4xx سيفشل بالطريقة نفسها.
أعد محاولة 5xx وانتهاء مهلة الشبكة مع تراجع أسي وحد أقصى، مثلاً 2 ثانية ثم 4 ثم 8، ثم توقف.
اضبط مهلة العميل أعلى بكثير من زمن الاستجابة المعتاد. تستخدم الأمثلة 120 ثانية لـ /extract.
بعد انتهاء المهلة في /extract لا تعرف هل نُفذت القراءة. تحقق من Documents بحثاً عن reference قبل إعادة الإرسال، أو اقبل التكرار.

البدء

المستندات (OCR)

التحقق والهوية الإلكترونية (eID)

تقييم المخاطر وتسجيل الجدارة

البناء

المرجع

أشكال الأخطاء

معرّف الطلب

الفهرس

400 طلب غير صالح

401 غير مصرح

403 محظور

404 غير موجود

413 الحمولة كبيرة جداً

422 تعذّرت المعالجة

429 طلبات كثيرة جداً

500 و502

إعادة المحاولة

​أشكال الأخطاء

​معرّف الطلب

​الفهرس

​400 طلب غير صالح

​401 غير مصرح

​403 محظور

​404 غير موجود

​413 الحمولة كبيرة جداً

​422 تعذّرت المعالجة

​429 طلبات كثيرة جداً

​500 و502

​إعادة المحاولة

أشكال الأخطاء

معرّف الطلب

الفهرس

400 طلب غير صالح

401 غير مصرح

403 محظور

404 غير موجود

413 الحمولة كبيرة جداً

422 تعذّرت المعالجة

429 طلبات كثيرة جداً

500 و502

إعادة المحاولة