توثيق واجهة Fileverity API

الأخطاء

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

عرض بصيغة Markdownآخر تحديث: 2026-11-04

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

{  "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.

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

النوع	الحالة	المعنى
`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.
أعد المحاولة بعد الانتظار عند idempotency_in_progress.
لا تُعِد المحاولة عند أخطاء 4xx الأخرى إلى أن تغيّر الطلب أو حالة الحساب.
لا تُحتسب رسوم على الفحص الذي ينتهي بخطأ.

ما زلت تواجه مشكلة؟ راسل hello@fileverity.com أو استخدم صفحة التواصل، وأرفق معرّف الطلب.

رموز الأخطاء

يُنشأ هذا الجدول من تعريفات الأخطاء في 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 النشطة. أبطل أحدها أولًا.

الأخطاء

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

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

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

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

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

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

رموز الأخطاء

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