كيف تُبنى استجابات الأخطاء في واجهة LinkHarbor API، وما معنى أهم رموز الأخطاء، وكيف ينبغي أن تتفاعل شيفرتك معها.

كل استجابة خطأ من الـ API لها التنسيق نفسه. ينبغي أن تعتمد شيفرتك على رمز الخطأ في الحقل error، لا على النص في message: فالرمز يبقى ثابتًا، أما النص فقد يتغير ويُترجم إلى لغة الحساب.

بنية استجابة الخطأ

مثال: 422 validation_failed

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error: رمز مقروء آليًا، مثل not_found. وفي معظم الأخطاء يوجد أيضًا في الترويسة X-Error-Code، لكن اعتمد على الحقل في الجسم.
message: وصف مقروء للبشر بلغة الحساب: مع مفتاح API لغة مالك مساحة العمل، ومع تطبيق متصل لغة الشخص الذي ربطه. وبدون رمز وصول صالح – مثلًا مع الخطأ 401 من فحص الرمز – تتبع اللغة Accept-Language، وإلا فهي الإنجليزية. وتذكر الترويسة Content-Language اللغة المستخدمة.
details: موجود فقط عندما يكون هناك ما يُضاف. في 422 الناتج عن التحقق من المدخلات يكون قائمة فيها field وreason وmessage لكل مشكلة؛ وفي 422 الناتج عن منطق العمل وفي كل الأخطاء الأخرى يكون كائنًا، مثلًا مع reason أو retry_after_sec أو قائمة issues. وعند تجاوز حجم ما يحتوي على field وreason وlimit، وفي 413 request_too_large على max_bytes وmax_kb. لذا تحقّق مما إذا كان details قائمة.
request_id: معرّف الطلب. وهو موجود أيضًا في الترويسة X-Request-Id. أرفقه عند التواصل مع الدعم.

الاستثناءات: استجابة 429 rate_limited فيها الحقل retry_after_sec بدلًا من details؛ ومع 429 و403 insufficient_scope يغيب request_id عن الجسم. وليس للخطأ 401 من فحص الرمز ولا للخطأ 422 من فحص المخطط ترويسة X-Error-Code، ومع فحص المخطط لا يُترجم إلا message في المستوى الأعلى، أما الرمز validation_failed فيبقى ثابتًا، والنصوص داخل details تبقى بالإنجليزية. أما الترويسة X-Request-Id فموجودة دائمًا.

أهم الرموز

HTTP	error	المعنى	ما العمل
400	invalid_json	الجسم ليس JSON صالحًا	تحقّق من JSON
400	bad_request	Content-Type خاطئ أو طلب مشوّه	اضبط Content-Type: application/json
401	missing_bearer_token	لا يوجد رمز في الترويسة Authorization	اضبط الترويسة Authorization: Bearer …
401	invalid_token	الرمز منتهي الصلاحية أو غير صالح، أو المفتاح محذوف	احصل على رمز جديد؛ وإذا لم يفد ذلك، فتحقّق من المفتاح
401	invalid_api_key	معرّف مفتاح أو سر خاطئ عند استبدال الرمز	تحقّق من بيانات الاعتماد
402	plan_limit_reached	تم بلوغ حد الخطة، مثلًا للروابط المختصرة	قم بالترقية أو احذف إدخالات
403	insufficient_scope	النطاق مفقود أو نقطة النهاية غير مفعّلة لمفاتيح API	أنشئ مفتاحًا بالنطاق الصحيح
403	forbidden	لا صلاحية لهذا الإجراء	نفّذه في لوحة التحكم
403	feature_not_available	الميزة غير مشمولة في الخطة	تحقّق من الخطة
403	block_type_requires_plan	نوع الكتلة متاح فقط في خطة أعلى	اختر نوع كتلة آخر أو قم بالترقية
403	template_locked	قالب مميز غير متاح في الخطة الحالية	اختر قالبًا من GET /v1/templates/available
403	workspace_suspended, workspace_read_only, workspace_grace_expired	مساحة العمل مقفلة أو للقراءة فقط بسبب دفعة مستحقة	سوِّ الدفع في لوحة التحكم
404	not_found	المورد غير موجود أو لا يتبع مساحة عملك	تحقّق من المعرّف
409	conflict	تعارض عام مع الحالة الحالية	أعد تحميل الحالة وغيّر المدخلات
409	workspace_template_in_use	قالب مساحة العمل ما زال مستخدمًا في صفحات؛ والعدد في details.count	انقل الصفحات إلى قالب آخر، ثم احذفه
409	handle_taken, slug_taken	المعرّف أو الـ slug للرابط المختصر مستخدم بالفعل	اختر قيمة أخرى
409	form_in_use, page_not_private, page_not_published, never_published	تعارض مع الحالة: النموذج ما زال على صفحة، أو الصفحة ليست خاصة أو غير منشورة، أو لم تُنشر قط	غيّر الحالة، ثم حاول مجددًا
409	page_limit_reached, link_limit_reached, block_limit_reached, form_limit_reached, asset_limit_reached, asset_storage_limit_reached, workspace_template_limit_reached	تم بلوغ حد الكمية أو التخزين في الخطة	أزل إدخالات أو قم بالترقية
409	draft_not_publishable	في المسودة مشكلات؛ والقائمة في details.issues	أصلح المشكلات، ثم انشر مجددًا
413	request_too_large	الجسم أكبر من المسموح لنقطة النهاية هذه (64 KB أو 1 MB أو 2 MB)؛ والحد في details.max_kb	أرسل بيانات أقل في كل طلب، انظر حدود المعدل
413	payload_too_large	الملف المرفوع أكبر من 10 MB	صغّر الملف
422	validation_failed	مدخلات غير صالحة أو حقل غير معروف؛ والتفاصيل في details	صحّح الحقول كما هو موضّح في details
422	handle_reserved, target_url_invalid, target_url_scheme, target_url_host	المعرّف محجوز، أو الرابط الهدف غير صالح أو غير مسموح	اختر قيمة أخرى
422	workspace_template_disabled	قالب مساحة العمل المحدد معطّل	فعّل القالب تحت «النطاقات والقوالب» أو اختر قالبًا آخر
422	template_css_external, template_section_invalid	قالب مساحة العمل: CSS يحمّل من خوادم خارجية، أو قسم {{#if}}/{{#unless}}/{{#each}} موضوع في مكان خاطئ	أزل العناوين الخارجية، أو أغلق القسم داخل الوسم نفسه أو النص نفسه
422	custom_css_external	CSS المخصص يحمّل شيئًا من خوادم خارجية	أزل العناوين الخارجية من CSS
429	rate_limited, api_key_locked	طلبات كثيرة جدًا، أو المفتاح مقفل بعد محاولات فاشلة	انتظر المدة التي يذكرها Retry-After أو details.retry_after_sec
500	internal_error	خطأ غير متوقع	حاول مجددًا لاحقًا، ودوّن request_id
503	service_unavailable	الخدمة غير متاحة مؤقتًا	حاول مجددًا بعد فاصل زمني

قراءة أخطاء المدخلات

مع 422 validation_failed تسرد details كل مشكلة على حدة: field هو مسار الحقل (بشرطات مائلة للكائنات المتداخلة، مثل theme_config/button_style)، وreason هي القاعدة التي خولفت، مثل required أو minLength أو maxLength أو enum أو additionalProperties. ومع additionalProperties تذكر الرسالة الحقول غير المعروفة، وغالبًا ما يكون السبب خطأً إملائيًا في اسم الحقل.

التعامل الموصى به في شيفرتك

400 و413 و422: لا تعد المحاولة، بل أصلح الطلب
401 invalid_token: احصل على رمز جديد مرة واحدة وأعد المحاولة
403: لا تعد المحاولة؛ تحقّق من النطاق أو الخطة أو ممّن يُسمح له بذلك
404: تحقّق من المعرّف؛ وبعد الحذف يكون هذا طبيعيًا
409: أعد تحميل الحالة وقرّر ما إذا كان الإجراء ما زال مطلوبًا
429: انتظر المدة التي يذكرها Retry-After، ثم أعد المحاولة، انظر حدود المعدل
500 و503: أعد المحاولة بضع مرات بفواصل متزايدة

لم تجد ما تبحث عنه؟

أخبرنا بما تحتاج إليه، وسيساعدك فريق الدعم لدينا شخصيًا.

تواصل مع الدعم

تنسيق أخطاء الـ API ورموز الأخطاء

#بنية استجابة الخطأ

#أهم الرموز

#قراءة أخطاء المدخلات

#التعامل الموصى به في شيفرتك

قد يفيدك أيضًا