--- title: "الملفات: دليل API فريقي" description: "ملفات المشروع والروابط الخارجية. معرّفات رقمية، ويستقبل مسار الحذف المسطّح معرّفاً ثابتاً (fil-). مسارات الملفات في REST API فريقي: البارامترات، وجسم الطلب" url: https://fareeqy.com/api/v1/docs/files language: ar --- # الملفات ملفات المشروع والروابط الخارجية. معرّفات رقمية، ويستقبل مسار الحذف المسطّح معرّفاً ثابتاً (fil-). عنوان الخدمة `https://app.fareeqy.com/api/v1` المحتويات في هذه الصفحة - شكل المورد - عرض مستوى واحد من متصفح ملفات المشروع - رفع ملف من محتوى مباشر - إضافة رابط خارجي - حذف ملف - حذف ملف بمعرّفه الثابت المسارات - [الحساب](https://fareeqy.com/api/v1/docs/account) - [الأحداث](https://fareeqy.com/api/v1/docs/events) - [المشاريع](https://fareeqy.com/api/v1/docs/projects) - [الأعضاء](https://fareeqy.com/api/v1/docs/members) - [قوائم المهام](https://fareeqy.com/api/v1/docs/task-lists) - [المهام](https://fareeqy.com/api/v1/docs/tasks) - [التعليقات](https://fareeqy.com/api/v1/docs/comments) - [المجلس](https://fareeqy.com/api/v1/docs/discussions) - [الملفات](https://fareeqy.com/api/v1/docs/files) - [المجلدات](https://fareeqy.com/api/v1/docs/folders) المزيد - [سجل التغييرات](https://fareeqy.com/api/v1/docs/changelog) في هذه الصفحة - شكل المورد - عرض مستوى واحد من متصفح ملفات المشروع - رفع ملف من محتوى مباشر - إضافة رابط خارجي - حذف ملف - حذف ملف بمعرّفه الثابت المسارات - [الحساب](https://fareeqy.com/api/v1/docs/account) - [الأحداث](https://fareeqy.com/api/v1/docs/events) - [المشاريع](https://fareeqy.com/api/v1/docs/projects) - [الأعضاء](https://fareeqy.com/api/v1/docs/members) - [قوائم المهام](https://fareeqy.com/api/v1/docs/task-lists) - [المهام](https://fareeqy.com/api/v1/docs/tasks) - [التعليقات](https://fareeqy.com/api/v1/docs/comments) - [المجلس](https://fareeqy.com/api/v1/docs/discussions) - [الملفات](https://fareeqy.com/api/v1/docs/files) - [المجلدات](https://fareeqy.com/api/v1/docs/folders) المزيد - [سجل التغييرات](https://fareeqy.com/api/v1/docs/changelog) ## شكل المورد الحقول التي ترجع داخل `data` في مسارات هذه المجموعة. `id` integer معرّف رقمي، فالملفات بلا slug. `url` string | null العنوان الكامل للصفحة التي يفتحها الشخص في فريقي. `name` string `path` string مسار المجلد الذي يوجد فيه الملف. `folder_id` integer | null `content_type` string | null `size_bytes` integer | null `size_human` string | null `external_url` string | null له قيمة في الرابط الخارجي، ويكون null في الملف المرفوع. `source` string | null الاسم المعروض للمصدر. `scan_state` string حالة فحص الفيروسات، مثل pending أو clean. `downloadable` boolean تصبح true بعد أن يجتاز الملف الفحص. `uploaded_by` string | null `created_at` string (date-time) ProjectFile نسخ `{ "id": 108, "url": "https://app.fareeqy.com/files/fil-3qd8n", "name": "الهوية-البصرية.pdf", "path": "التصاميم/الهوية-البصرية.pdf", "folder_id": 42, "content_type": "application/pdf", "size_bytes": 2418176, "size_human": "2.31 م.بايت", "external_url": null, "source": null, "scan_state": "clean", "downloadable": true, "uploaded_by": "سارة العتيبي", "created_at": "2026-07-10T16:31:44.000+03:00" }` ### عرض مستوى واحد من متصفح ملفات المشروع GET /projects/ {project\_id} /files يتطلب `files:read` المجلدات والملفات الموجودة مباشرة داخل `folder_id`، أو في جذر المشروع. ليست تنازلية: انزل مستوى بإرسال معرّف المجلد الفرعي. الملفات مقسّمة إلى صفحات، والمجلدات ليست كذلك. #### بارامترات المسار `project_id` string مطلوب المعرّف الثابت للمشروع، أو الـ slug الخاص به. #### بارامترات الاستعلام `folder_id` integer المجلد الذي تعرض محتواه. اتركه لعرض جذر المشروع. `limit` integer حجم الصفحة. الافتراضي 50، والحد الأقصى 100، وما زاد عنه يُقصَر عليه. الافتراضي: `50` `offset` integer عدد السجلات التي تُتخطّى. الافتراضي 0. الافتراضي: `0` #### مثال الطلب cURL نسخ `curl "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/files" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### مثال الاستجابة 200 نسخ `{ "data": { "folder": { "id": 42, "url": "https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=42", "name": "التصاميم", "path": "التصاميم", "description": "ملفات الهوية وواجهات الموقع.", "parent_folder_id": null, "created_at": "2026-07-05T08:20:00.000+03:00" }, "folders": [ { "id": 51, "url": "https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=51", "name": "الأيقونات", "path": "التصاميم/الأيقونات", "description": null, "parent_folder_id": 42, "created_at": "2026-07-06T09:02:14.000+03:00" } ], "files": [ { "id": 108, "url": "https://app.fareeqy.com/files/fil-3qd8n", "name": "الهوية-البصرية.pdf", "path": "التصاميم/الهوية-البصرية.pdf", "folder_id": 42, "content_type": "application/pdf", "size_bytes": 2418176, "size_human": "2.31 م.بايت", "external_url": null, "source": null, "scan_state": "clean", "downloadable": true, "uploaded_by": "سارة العتيبي", "created_at": "2026-07-10T16:31:44.000+03:00" }, { "id": 131, "url": "https://app.fareeqy.com/files/fil-7mk2w", "name": "واجهات الصفحة الرئيسية", "path": "التصاميم/واجهات الصفحة الرئيسية", "folder_id": 42, "content_type": null, "size_bytes": null, "size_human": null, "external_url": "https://www.figma.com/design/9aZq/home-v3", "source": "Figma", "scan_state": "skipped", "downloadable": true, "uploaded_by": "سارة العتيبي", "created_at": "2026-07-12T11:04:20.000+03:00" }, { "id": 147, "url": "https://app.fareeqy.com/files/fil-2bz6r", "name": "لقطة-الصفحة-الرئيسية.png", "path": "التصاميم/لقطة-الصفحة-الرئيسية.png", "folder_id": 42, "content_type": "image/png", "size_bytes": 884736, "size_human": "864 ك.بايت", "external_url": null, "source": null, "scan_state": "clean", "downloadable": true, "uploaded_by": "عبدالله المطيري", "created_at": "2026-07-14T10:22:07.000+03:00" }, { "id": 152, "url": "https://app.fareeqy.com/files/fil-9pd4h", "name": "عرض-التدفق-الجديد.mp4", "path": "التصاميم/عرض-التدفق-الجديد.mp4", "folder_id": 42, "content_type": "video/mp4", "size_bytes": 41943040, "size_human": "40 م.بايت", "external_url": null, "source": null, "scan_state": "pending", "downloadable": false, "uploaded_by": "نورة الحربي", "created_at": "2026-07-15T13:47:58.000+03:00" } ] }, "meta": { "total": 4, "limit": 50, "offset": 0 } }` حالات الرفض: 401 403 404 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض 401 `default` Missing or invalid API key. default نسخ `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry. This key may not perform this operation نسخ `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access نسخ `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach. A record that is missing or out of reach نسخ `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint نسخ `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_limit_exceeded` Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": ""}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string. Today's daily allowance is spent (application envelope) نسخ `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) نسخ `{ "error": "Rate limit exceeded. Please try again later." }` [الأخطاء](https://fareeqy.com/api/v1/docs#errors) ### رفع ملف من محتوى مباشر POST /projects/ {project\_id} /files يتطلب `files:write` يرفع ملفاً من `content` وهو نص UTF-8، أو من `content_base64` وهو ثنائي بترميز base64 قياسي بلا فواصل أسطر. أحدهما فقط، لا كلاهما. والحد 5 م.بايت بعد فك الترميز. الملف المرفوع حديثاً يبقى `pending` وغير قابل للتنزيل حتى يجتاز فحص الفيروسات. #### بارامترات المسار `project_id` string مطلوب المعرّف الثابت للمشروع، أو الـ slug الخاص به. #### جسم الطلب `name` string مطلوب اسم الملف مع امتداده. `folder_id` integer | null المجلد الوجهة. اتركه للرفع في جذر المشروع. `content` string | null محتوى نصي بترميز UTF-8. أرسله أو أرسل `content_base64`، لا كليهما. `content_base64` string | null بايتات بترميز base64. أرسله أو أرسل `content`، لا كليهما. #### مثال الطلب cURL نسخ `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/files" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"","folder_id":null,"content":null,"content_base64":null}'` #### مثال الاستجابة 201 نسخ `{ "data": { "id": 108, "url": "https://app.fareeqy.com/files/fil-3qd8n", "name": "الهوية-البصرية.pdf", "path": "التصاميم/الهوية-البصرية.pdf", "folder_id": 42, "content_type": "application/pdf", "size_bytes": 2418176, "size_human": "2.31 م.بايت", "external_url": null, "source": null, "scan_state": "clean", "downloadable": true, "uploaded_by": "سارة العتيبي", "created_at": "2026-07-10T16:31:44.000+03:00" } }` حالات الرفض: 401 403 404 409 422 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض 401 `default` Missing or invalid API key. default نسخ `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry. This key may not perform this operation نسخ `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access نسخ `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach. A record that is missing or out of reach نسخ `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint نسخ `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default نسخ `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default نسخ `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_limit_exceeded` Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": ""}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string. Today's daily allowance is spent (application envelope) نسخ `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) نسخ `{ "error": "Rate limit exceeded. Please try again later." }` [الأخطاء](https://fareeqy.com/api/v1/docs#errors) ### إضافة رابط خارجي POST /projects/ {project\_id} /files/link يتطلب `files:write` يضيف رابطاً خارجياً (Figma، أو Drive، أو Notion..) بلا تخزين، ولا فحص، ولا حدّ للحجم. ويُتحقق من نطاق الرابط مقابل `source_type`. #### بارامترات المسار `project_id` string مطلوب المعرّف الثابت للمشروع، أو الـ slug الخاص به. #### جسم الطلب `name` string مطلوب `url` string (uri) مطلوب `source_type` string مطلوب الجهة التي يشير إليها الرابط الخارجي، ويُتحقق من نطاقه. القيم: `notion` `google_drive` `dropbox` `onedrive` `box` `figma` `sketch` `zoho` `other` `folder_id` integer | null المجلد الوجهة. اتركه للرفع في جذر المشروع. #### مثال الطلب cURL نسخ `curl -X POST "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/files/link" \ -H "Authorization: Bearer $FAREEQY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"","url":"","source_type":"notion","folder_id":null}'` #### مثال الاستجابة 201 نسخ `{ "data": { "id": 108, "url": "https://app.fareeqy.com/files/fil-3qd8n", "name": "الهوية-البصرية.pdf", "path": "التصاميم/الهوية-البصرية.pdf", "folder_id": 42, "content_type": "application/pdf", "size_bytes": 2418176, "size_human": "2.31 م.بايت", "external_url": null, "source": null, "scan_state": "clean", "downloadable": true, "uploaded_by": "سارة العتيبي", "created_at": "2026-07-10T16:31:44.000+03:00" } }` حالات الرفض: 401 403 404 409 422 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض 401 `default` Missing or invalid API key. default نسخ `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry. This key may not perform this operation نسخ `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access نسخ `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach. A record that is missing or out of reach نسخ `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint نسخ `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 409 `default` A uniqueness/record conflict; retry. default نسخ `{ "error": { "code": "conflict", "message": "تعذّر إتمام العملية بسبب تعارض. أعد المحاولة." } }` 422 `default` A caller-fixable bad request (validation error, bad date, bad enum). default نسخ `{ "error": { "code": "unprocessable_entity", "message": "قيمة due_at غير صالحة؛ أرسل تاريخاً مثل 2026-07-20. المهمة تُستحق في يوم، وأي وقت ترسله يُهمل." } }` 429 `rate_limit_exceeded` Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": ""}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string. Today's daily allowance is spent (application envelope) نسخ `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) نسخ `{ "error": "Rate limit exceeded. Please try again later." }` [الأخطاء](https://fareeqy.com/api/v1/docs#errors) ### حذف ملف DELETE /projects/ {project\_id} /files/ {id} يتطلب `files:destructive` حذف نهائي. #### بارامترات المسار `project_id` string مطلوب المعرّف الثابت للمشروع، أو الـ slug الخاص به. `id` string مطلوب المعرّف الثابت للملف (fil-8f3kd)، أو معرّفه الرقمي. والملفات لم يكن لها slug أصلاً. #### مثال الطلب cURL نسخ `curl -X DELETE "https://app.fareeqy.com/api/v1/projects/prj-8f3kd/files/108" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### مثال الاستجابة 200 نسخ `{ "data": { "deleted": true, "file": { "id": 108, "name": "الهوية-البصرية.pdf" } } }` حالات الرفض: 401 403 404 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض 401 `default` Missing or invalid API key. default نسخ `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry. This key may not perform this operation نسخ `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access نسخ `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach. A record that is missing or out of reach نسخ `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint نسخ `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_limit_exceeded` Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": ""}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string. Today's daily allowance is spent (application envelope) نسخ `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) نسخ `{ "error": "Rate limit exceeded. Please try again later." }` [الأخطاء](https://fareeqy.com/api/v1/docs#errors) ### حذف ملف بمعرّفه الثابت DELETE /files/ {id} يتطلب `files:destructive` حذف نهائي. ولا يوجد `get` ولا `patch` مسطّح: قائمة الملفات تتبع مشروعها ومجلدها، وليس للملف تعديل على هذا السطح، فالحذف هو كل ما يصلح له عنوانه الخاص. #### بارامترات المسار `id` string مطلوب المعرّف الثابت للملف (fil-3qd8n). ولا يُقبل المعرّف الرقمي هنا. #### مثال الطلب cURL نسخ `curl -X DELETE "https://app.fareeqy.com/api/v1/files/fil-3qd8n" \ -H "Authorization: Bearer $FAREEQY_API_KEY"` #### مثال الاستجابة 200 نسخ `{ "data": { "deleted": true, "file": { "id": 41, "name": "عقد-الموردين.pdf" } } }` حالات الرفض: 401 403 404 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض 401 `default` Missing or invalid API key. default نسخ `{ "error": { "code": "unauthorized", "message": "مفتاح الـ API غير صالح أو غير مُرسَل." } }` 403 `forbidden` Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry. This key may not perform this operation نسخ `{ "error": { "code": "forbidden", "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية." } }` The company's plan carries no API access نسخ `{ "error": { "code": "plan_upgrade_required", "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله." } }` 404 `not_found` Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach. A record that is missing or out of reach نسخ `{ "error": { "code": "not_found", "message": "غير موجود، أو لا تملك صلاحية الوصول إليه." } }` A path that matches no endpoint نسخ `{ "error": { "code": "unknown_endpoint", "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API." } }` 429 `rate_limit_exceeded` Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": ""}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string. Today's daily allowance is spent (application envelope) نسخ `{ "error": { "code": "rate_limit_exceeded", "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh." } }` Over 300 requests in a minute (Rack::Attack body, flat error) نسخ `{ "error": "Rate limit exceeded. Please try again later." }` [الأخطاء](https://fareeqy.com/api/v1/docs#errors) [السابق المجلس](https://fareeqy.com/api/v1/docs/discussions) [التالي المجلدات](https://fareeqy.com/api/v1/docs/folders)