> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahlfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# الأخطاء

> جميع أجسام الأخطاء التي تعيدها Partner API، مع الحالة والسبب والحل.

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

هناك ثلاثة أشكال. اقرأ الحالة أولاً ثم الجسم.

**1. `detail` نص** (معظم الأخطاء).

```json theme={null}
{ "detail": "Invalid or revoked API key" }
```

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

```json theme={null}
{
  "detail": {
    "code": "kyc_extract_cap_reached",
    "message": "Monthly document-read limit of 2000 reached.",
    "used": 2000,
    "limit": 2000
  }
}
```

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

```json theme={null}
{ "code": "rate_limit_exceeded", "message": "Too many requests. Please slow down." }
```

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

```json theme={null}
{
  "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"` (نص، ويتغير اسم النطاق) | لا يملك المفتاح النطاق المطلوب لنقطة النهاية. | أنشئ مفتاحاً بهذا النطاق. راجع [النطاقات](/ar/authentication). |
| `{"code": "kyc_scope_not_allowed", "message": "This workspace is not enabled for the partner KYC API."}` | يحمل المفتاح نطاق `kyc:` لكن مساحة العمل غير مفعّلة. الوصول إلى Partner API يتم لكل مساحة عمل. | [اطلب الوصول إلى sandbox](https://sahlfinancial.com/contact?type=demo). |
| `{"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](https://sahlfinancial.com/contact?type=demo) لإعداد 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`. راجع [قراءة المستندات](/ar/guides/ocr-documents).

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

لا يوفر 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` قبل إعادة الإرسال، أو اقبل التكرار.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.