الأخطاء

كل خطأ يأتي مع حالة HTTP وغلاف JSON نفسه. code هو العقد الذي تقرؤه شيفرتك؛ أما message فمكتوبة للبشر وقد تتغير.

json

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

يوضح details أكثر: الحقل المرفوض، وسبب الشبكة، ونافذة الحد المستنفدة.
يقود docUrl إلى شرح الرمز في هذه الصفحة.
يعرّف requestId الطلب: أعطه للدعم.

تجيب نقاط نهاية OAuth (/v1/oauth/token، /v1/oauth/authorize) بصيغة RFC 6749: { "error": "invalid_grant", "error_description": "…" }.

رموز الأخطاء

الحالة	الرمز	المعنى
400	`invalid_request`	الجسم أو الاستعلام أو معامل غير صالح. تفصيل واحد لكل حقل مرفوض: `field` و`code` (`required` و`is_string` و`max`…) و`message`.
400	`invalid_json`	الجسم ليس JSON صالحًا.
400	`invalid_cursor`	المؤشر لم تُعدْه Sofia API.
400	`webhook_url_invalid`	عنوان webhook ليس https، أو يقود إلى عنوان خاص.
400	`webhook_event_invalid`	حدث webhook غير معروف.
400	`application_name_invalid`	الإعدادات › API: اسم العميل مفقود أو طويل جدًا.
400	`application_profile_invalid`	الإعدادات › API: حقل في ملف العميل غير صالح؛ وتذكره التفاصيل.
400	`logo_invalid`	الإعدادات › API: الشعار مرفوض (180×180 px على الأقل، بصيغة PNG أو JPEG أو WebP، و2 MB كحد أقصى).
401	`invalid_token`	الرمز مفقود أو غير معروف أو منتهي أو ملغى، أو أن الشخص الذي وراءه فقد الصلاحيات التي يحملها. راجع الترويسة `WWW-Authenticate`.
401	`unauthorized`	المصادقة مطلوبة.
402	`subscription_required`	الكتابة الحية (بما فيها التجربة الجافة) تتطلب اشتراكًا نشطًا أو فترة تجريبية.
403	`insufficient_scope`	الرمز يفتقر إلى نطاق نقطة النهاية؛ ويسميه التفصيل.
403	`insufficient_role`	دورك في مساحة العمل هذه لا يسمح بهذا الإجراء.
403	`live_mode_required`	كتابة حقيقية برمز اختبار.
403	`route_closed_to_applications`	نقطة النهاية هذه غير مفتوحة للتطبيقات.
403	`forbidden`	الوصول مرفوض.
403	`session_required`	الإعدادات › API: يتطلب هذا الإجراء جلسة Sofia وليس رمزًا.
403	`impersonation_forbidden`	الإعدادات › API: هذا الإجراء مرفوض في جلسة مستعارة.
403	`workspace_owner_required`	وحده مالك مساحة العمل (Workspace) يستطيع فعل ذلك.
403	`workspace_member_required`	أنت لست عضوًا في مساحة العمل (Workspace) هذه.
404	`route_not_found`	لا توجد نقطة نهاية تجيب عن هذه الطريقة وهذا المسار.
404	`establishment_not_found`	منشأة غير معروفة، أو خارج متناول الرمز.
404	`media_not_found`	وسائط غير معروفة، أو خارج متناول الرمز.
404	`post_not_found`	منشور غير معروف، أو خارج متناول الرمز.
404	`webhook_not_found`	webhook غير معروف، أو يخص تطبيقًا آخر.
404	`not_found`	المورد غير موجود.
404	`application_not_found`	الإعدادات › API: عميل غير معروف.
404	`grant_not_found`	تفويض غير معروف أو ملغى بالفعل.
404	`personal_key_not_found`	الإعدادات › API: مفتاح شخصي غير معروف.
404	`consent_not_found`	انتهى طلب التفويض أو لا وجود له: ابدأ من جديد من نقطة نهاية التفويض.
405	`method_not_allowed`	هذه الطريقة غير مسموح بها على نقطة النهاية هذه.
409	`post_in_flight`	شبكة ترسل المنشور: أعد محاولة الحذف بعد قليل.
409	`post_not_editable`	أرسلت شبكة المنشور بالفعل: لم يعد قابلًا للتعديل.
409	`account_already_connected`	هذه الشبكة متصلة بالفعل بالمنشأة.
409	`webhook_limit_reached`	لدى التطبيق بالفعل 10 webhooks.
409	`idempotency_in_progress`	الطلب الأول بهذا `Idempotency-Key` لا يزال قيد التنفيذ.
409	`conflict`	يتعارض الطلب مع الحالة الحالية للمورد.
409	`scope_removal_forbidden`	الإعدادات › API: يمكن إضافة صلاحية إلى عميل لكن لا يمكن إزالتها.
409	`public_client_has_no_secret`	الإعدادات › API: العميل العام ليس له سر.
413	`payload_too_large`	الملف أكبر من حد الرفع.
415	`unsupported_media_type`	نوع محتوى غير مدعوم.
422	`post_refused`	شبكة أو المنشأة أو باقتك سترفض المنشور. تفصيل واحد لكل سبب، لكل منها `message` خاصة به.
422	`media_import_refused`	تعذّر استيراد الوسائط من هذا الرابط؛ ويذكر التفصيل السبب.
422	`media_upload_refused`	الملف المرفوع ليس صورة أو فيديو مدعومًا.
422	`platform_not_offered`	هذه الشبكة غير متاحة للربط.
422	`idempotency_key_reused`	استُخدم هذا `Idempotency-Key` مع جسم مختلف.
422	`unprocessable_entity`	الطلب مفهوم لكن لا يمكن معالجته.
429	`rate_limit_exceeded`	نافذة حد المعدل ممتلئة: انتظر انقضاء `Retry-After`.

أسباب رفض المنشور

يسرد post_refused كل سبب في details[].code:

الرمز	المعنى
`unsupported_platform`	هذه الشبكة غير مدعومة.
`duplicate_platform`	ذُكرت الشبكة نفسها مرتين.
`unsupported_format`	هذه الشبكة لا تقدم هذه الصيغة.
`caption_too_long`	النص طويل جدًا (`max`، `actual`).
`too_many_hashtags`	هاشتاغات كثيرة جدًا (`max`، `actual`).
`too_many_mentions`	إشارات كثيرة جدًا (`max`، `actual`).
`too_many_thread_posts`	السلسلة طويلة جدًا (`max`، `actual`).
`too_many_media`	وسائط كثيرة جدًا (`max`، `actual`).
`media_mix_refused`	لا يمكن الجمع بين الصور والفيديوهات على هذه الشبكة.
`media_required`	تتطلب هذه الشبكة صورة أو فيديو.
`media_type_refused`	هذه الشبكة لا تقبل هذا النوع من الوسائط.
`scheduled_in_past`	`scheduledAt` في الماضي.
`scheduled_at_invalid`	المنشور المجدول يحتاج إلى `scheduledAt` في المستقبل.
`account_not_connected`	لا يوجد حساب متصل على هذه الشبكة لهذه المنشأة.
`account_ambiguous`	عدة حسابات متصلة على هذه الشبكة: سمِّ أحدها بـ `accountId`.
`media_not_found`	الوسائط ليست في مكتبة هذه المنشأة.
`media_url_invalid`	يجب أن يكون رابط الوسائط عنوان https عامًا.
`platform_unavailable`	هذه الشبكة غير مفتوحة على Sofia بعد.
`publication_quota_exceeded`	بلغت حصة النشر في باقتك.

التعامل مع الأخطاء

تفرّع بحسب code، لا بحسب message أبدًا.
أعد محاولة 429 بعد Retry-After، و5xx بتراجع أسّي (exponential backoff).
لا تعد محاولة 4xx دون تغيير أبدًا: أصلح الطلب أولًا.
سجّل requestId مع كل فشل.