# الأخطاء

> صيغة الأخطاء في Fileverity API، ورموز حالة HTTP، والجدول الكامل لرموز الأخطاء، مع إرشادات حول الأخطاء التي تستحق إعادة المحاولة.

المصدر: https://fileverity.com/ar/docs/errors

تستخدم الأخطاء رمز حالة HTTP قياسيًا ومحتوى استجابة بصيغة JSON يتضمن `code` ثابتًا. اعتمد على `code` في معالجة الخطأ، لا على `message`، فقد تتغير الرسائل.

**استجابة الخطأ**

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Unrecognized parameter: files.",
    "param": "files",
    "request_id": "req_4mQ9cX2vB7nP1sK8tL3wR6yZ"
  }
}
```

| الحقل | الوصف |
| --- | --- |
| `error.type` | الفئة. يقابل كل نوع مجموعة واحدة من رموز حالة HTTP، وهي مدرجة أدناه. |
| `error.code` | معرّف ثابت قابل للقراءة آليًا. |
| `error.message` | شرح مكتوب ليقرأه البشر. وقد يذكر الحقل أو الحد المعني. |
| `error.param` | حقل الطلب الذي تسبب في الخطأ، أو `null`. |
| `error.request_id` | معرّف هذا الطلب، وهو موجود أيضًا في ترويسة الاستجابة `x-request-id`. اذكره عند التواصل مع الدعم عبر [hello@fileverity.com](mailto:hello@fileverity.com). |

## أنواع الأخطاء

| النوع | الحالة | المعنى |
| --- | --- | --- |
| `invalid_request_error` | 400, 413, 415, 422 | الطلب غير صحيح الصيغة أو يتجاوز حدًا. صحّح الطلب؛ فإعادة إرساله دون تغيير تفشل مرة أخرى. |
| `authentication_error` | 401 | مفتاح API مفقود أو غير صالح. |
| `billing_error` | 402 | الرصيد أو حد الإنفاق يمنع تنفيذ الطلب. أضف رصيدًا أو ارفع الحد. |
| `not_found_error` | 404 | المورد غير موجود أو انتهت صلاحيته أو يتبع مساحة عمل أخرى. |
| `conflict_error` | 409 | يتعارض الطلب مع الحالة الراهنة. |
| `rate_limit_error` | 429 | عدد الطلبات كبير جدًا أو عدد عمليات الرفع المعلقة كبير جدًا. وفي حالة `rate_limited`، انتظر عدد الثواني الوارد في `retry-after`. أما `pending_files_limit` فلا تحمل `retry-after`: استخدم الملفات أو احذفها أو انتظر انتهاء صلاحيتها. |
| `api_error` | 500, 502, 503 | مشكلة من جانبنا أو ازدحام في الخدمة. لم تُحتسب رسوم على هذه الطلبات. أعد المحاولة مع زيادة مدة الانتظار تدريجيًا (backoff). وتحمل `service_unavailable` الترويسة `retry-after`. |

## ما الذي تُعاد محاولته

- **أعد المحاولة** عند `rate_limited` بعد المدة (بالثواني) المحددة في `retry-after`، وعند `internal_error` و`analysis_failed` و`service_unavailable` مع زيادة الانتظار أسّيًا (exponential backoff؛ وفي حالة `service_unavailable` ابدأ بالمدة المحددة في `retry-after`). أرسل `Idempotency-Key` نفسه حتى لا يُنفَّذ الطلب مرتين عند إعادة المحاولة. راجع [Idempotency](https://fileverity.com/ar/docs/idempotency.md).
- **أعد المحاولة بعد الانتظار** عند `idempotency_in_progress`.
- **لا تُعِد المحاولة** عند أخطاء `4xx` الأخرى إلى أن تغيّر الطلب أو حالة الحساب.
- لا تُحتسب رسوم على الفحص الذي ينتهي بخطأ.

ما زلت تواجه مشكلة؟ راسل [hello@fileverity.com](mailto:hello@fileverity.com) أو استخدم [صفحة التواصل](https://fileverity.com/ar/contact)، وأرفق معرّف الطلب.

## رموز الأخطاء

يُنشأ هذا الجدول من تعريفات الأخطاء في API نفسها.

| الرمز | الحالة | النوع | الرسالة |
| --- | --- | --- | --- |
| `invalid_json` | 400 | `invalid_request_error` | يجب أن يكون محتوى الطلب كائن JSON. |
| `missing_parameter` | 400 | `invalid_request_error` | معلمة مطلوبة مفقودة. |
| `invalid_parameter` | 400 | `invalid_request_error` | قيمة إحدى المعلمات غير صالحة. |
| `text_too_short` | 400 | `invalid_request_error` | النص أقصر من أن يُقيَّم. أرسل 100 كلمة على الأقل. |
| `text_too_long` | 413 | `invalid_request_error` | يتجاوز النص 100,000 حرف. قسّمه إلى عدة طلبات. |
| `unsupported_media_type` | 415 | `invalid_request_error` | أرسل محتوى الطلب بصيغة JSON مع الترويسة "Content-Type: application/json". |
| `unsupported_language` | 400 | `invalid_request_error` | النص ليس بلغة مدعومة. اللغات المدعومة هي en وfr وde وes وzh. |
| `file_not_found` | 400 | `invalid_request_error` | لم يُعثر على الملف المرفوع أو انتهت صلاحيته. ارفعه مرة أخرى. |
| `unsupported_file` | 415 | `invalid_request_error` | صيغة الملف غير مدعومة لهذا النموذج. |
| `file_too_large` | 413 | `invalid_request_error` | يتجاوز الملف حد الحجم المسموح به لهذا النموذج. |
| `too_many_pixels` | 413 | `invalid_request_error` | تتجاوز الصورة 40 ميغابكسل. |
| `too_many_pages` | 413 | `invalid_request_error` | يتجاوز المستند 100 صفحة. |
| `document_too_long` | 413 | `invalid_request_error` | يحتوي المستند على نص أكثر مما يمكن تحليله في طلب واحد. |
| `invalid_file` | 422 | `invalid_request_error` | الملف تالف أو لا يمكن قراءته. |
| `password_required` | 422 | `invalid_request_error` | المستند مشفّر. أرسل كلمة مروره لتحليله. |
| `wrong_password` | 422 | `invalid_request_error` | كلمة مرور المستند غير صحيحة. |
| `not_examinable` | 422 | `invalid_request_error` | لا يحتوي المستند على نص أو صور أو بنية يمكن فحصها. لم تُحتسب عليك أي رسوم. |
| `missing_api_key` | 401 | `authentication_error` | لم يُقدَّم مفتاح API. أرسله في الترويسة "Authorization: Bearer fv_live_...". |
| `invalid_api_key` | 401 | `authentication_error` | مفتاح API غير صالح أو أُبطل. |
| `insufficient_balance` | 402 | `billing_error` | رصيدك غير كافٍ لهذا الطلب. أضف رصيدًا في لوحة التحكم. |
| `spend_limit_reached` | 402 | `billing_error` | بلغ مفتاح API هذا حد الإنفاق الشهري. ارفع الحد في لوحة التحكم أو انتظر حتى الشهر التالي (UTC). |
| `not_found` | 404 | `not_found_error` | المورد المطلوب غير موجود. |
| `model_not_found` | 404 | `not_found_error` | النموذج غير موجود أو غير متاح. |
| `not_cancelable` | 409 | `conflict_error` | لم يعد بالإمكان إلغاء التحليل. |
| `canceled` | 409 | `conflict_error` | أُلغي التحليل. لم تُحتسب عليك أي رسوم. |
| `idempotency_mismatch` | 409 | `conflict_error` | سبق استخدام Idempotency-Key هذا مع محتوى طلب مختلف. |
| `idempotency_in_progress` | 409 | `conflict_error` | لا يزال الطلب الذي يحمل Idempotency-Key هذا قيد المعالجة. أعد المحاولة بعد قليل. |
| `pending_files_limit` | 429 | `rate_limit_error` | تضم مساحة العمل هذه عددًا كبيرًا جدًا من الملفات المرفوعة المعلّقة. حلّل الملفات المرفوعة أو احذفها، أو انتظر حتى 24 ساعة لتنتهي صلاحيتها. |
| `rate_limited` | 429 | `rate_limit_error` | عدد الطلبات كبير جدًا. أعد المحاولة بعد عدد الثواني المذكور في الترويسة Retry-After. |
| `internal_error` | 500 | `api_error` | تعذّر إكمال الطلب. أعد المحاولة؛ وإذا استمرت المشكلة فتواصل مع الدعم مع ذكر معرّف الطلب. |
| `analysis_failed` | 502 | `api_error` | تعذّر إكمال التحليل. لم تُحتسب عليك أي رسوم؛ أعد المحاولة، وتواصل مع الدعم مع ذكر معرّف الطلب إذا فشل مرة أخرى. |
| `service_unavailable` | 503 | `api_error` | الخدمة غير متاحة مؤقتًا أو أن السعة المتاحة مستخدمة بالكامل. لم تُحتسب عليك أي رسوم؛ أعد المحاولة بعد عدد الثواني المذكور في الترويسة Retry-After. |

## رموز خاصة بلوحة التحكم فقط

تعيد نقاط النهاية الخاصة بلوحة التحكم هذه الرموز، وهي تعمل بجلسة تسجيل دخولك. ولا تعيدها الطلبات المنفّذة بمفتاح API.

| الرمز | الحالة | النوع | الرسالة |
| --- | --- | --- | --- |
| `session_required` | 401 | `authentication_error` | سجّل الدخول للمتابعة. |
| `forbidden` | 403 | `permission_error` | ليست لديك صلاحية لتنفيذ هذا الإجراء. |
| `invite_invalid` | 404 | `not_found_error` | هذه الدعوة غير صالحة أو منتهية الصلاحية أو سبق استخدامها. |
| `invite_mismatch` | 403 | `permission_error` | أُرسلت هذه الدعوة إلى عنوان بريد إلكتروني آخر. |
| `invite_limit` | 409 | `conflict_error` | بلغت مساحة العمل هذه الحد الأقصى من الدعوات المعلّقة. أبطل إحداها أولًا. |
| `last_owner` | 409 | `conflict_error` | يجب أن تحتفظ مساحة العمل بمالك واحد على الأقل. عيّن عضوًا آخر مالكًا أولًا. |
| `webhook_limit` | 409 | `conflict_error` | بلغت مساحة العمل هذه الحد الأقصى من نقاط نهاية Webhook. احذف إحداها أولًا. |
| `key_limit` | 409 | `conflict_error` | بلغت مساحة العمل هذه الحد الأقصى من مفاتيح API النشطة. أبطل أحدها أولًا. |