المفاهيم

الأخطاء

تستخدم الأخطاء رموز حالة HTTP القياسية ولها دائمًا بنية JSON نفسها.

تنسيق الخطأ#

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not have the scope posts:write"
  }
}

code ثابت: استخدمه في شيفرتك.
message موجّه للبشر وقد يتغيّر.
تضيف بعض الأخطاء حقولًا إضافية بجانب code وmessage (مثلًا الحقل غير الصالح في خطأ التحقق).

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

الحالة	الرمز	المعنى · ما يجب فعله
400	`VALIDATION_ERROR`	معامل أو حقل في جسم الطلب مفقود أو غير صالح. صحّح الطلب، ولا تُعِد المحاولة كما هو.
400	`INVALID_JSON`	جسم الطلب ليس JSON صالحًا. أرسل `Content-Type: application/json` وجسمًا صالحًا.
401	`INVALID_API_KEY`	مفتاح مفقود أو مشوّه أو ملغى. تحقق من الترويسة `Authorization`.
403	`INSUFFICIENT_SCOPE`	لا يملك المفتاح نطاق الصلاحية الذي تحتاجه نقطة النهاية هذه. أنشئ مفتاحًا بـنطاقات الصلاحية الصحيحة.
403	`DEVELOPER_ACCESS_REVOKED`	تم تعليق وصول المطوّرين لهذا الحساب أو إلغاؤه. تواصل مع developers@linework.app.
403	`PROFILE_INCOMPLETE`	أضف صورة ملف شخصي وصورة غلاف إلى الحساب قبل استخدام نقاط نهاية الكتابة.
403	`CHAT_NOT_ALLOWED`	قاعدة مكافحة الرسائل المزعجة لا تسمح بهذه الرسالة: لم يراسلك الشخص ولا يتابعك.
403	`CHAT_BLOCKED`	أحدكما حظر الآخر. لا تُعِد المحاولة.
403	`STORE_BLOCKED`	هذا المتجر حظرك.
403	`USER_UNAVAILABLE`	المستخدم غير متاح (محظور، أو خاص، أو معلّق).
403	`FORBIDDEN`	الإجراء غير مسموح به لهذا الحساب (مثلًا تعديل منشور شخص آخر).
404	`NOT_FOUND`	المورد غير موجود أو لا يمكنك رؤيته.
409	`CONFLICT`	يتعارض الطلب مع الحالة الحالية (مثلًا شحن طلب مرتين).
413	`PAYLOAD_TOO_LARGE`	جسم الطلب أو الملف المرفوع كبير جدًا. راجع حدود الوسائط في النشر مع الوسائط.
429	`RATE_LIMITED`	طلبات كثيرة جدًا، أو تم استنفاد حصة يومية. انتظر مدة `Retry-After`. راجع حدود المعدّل.
500	`INTERNAL_ERROR`	حدث خطأ ما من جهتنا. أعد المحاولة لاحقًا مع التراجع التدريجي (backoff).

قد تُضاف رموز جديدة مع الوقت: تعامل مع أي رمز غير معروف بالمعنى العام لحالة HTTP الخاصة به.

إعادة المحاولة أم لا؟#

الحالة	إعادة المحاولة؟
400, 401, 403, 404, 409, 413	لا. صحّح الطلب أو المفتاح أو الحساب أولًا.
429	نعم، بعد مدة `Retry-After`.
500, 502, 503, 504	نعم، مع التراجع الأُسّي (exponential backoff). بالنسبة لعمليات الكتابة غير المتساوية القوة (non-idempotent) (مثلًا `POST /posts`)، تحقق أولًا من أن الإجراء لم يحدث بالفعل.

مثال على معالج الأخطاء#

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json().catch(() => ({ error: { code: "UNKNOWN" } }));
  switch (error.code) {
    case "RATE_LIMITED": /* wait Retry-After, then retry */ break;
    case "INVALID_API_KEY":
    case "DEVELOPER_ACCESS_REVOKED": /* stop the bot and alert someone */ break;
    case "CHAT_NOT_ALLOWED": /* skip this user */ break;
    default: throw new Error(`${res.status} ${error.code}: ${error.message}`);
  }
}

r = s.post(url, json=body, timeout=30)  # s = requests.Session() with the Authorization header
if not r.ok:
    err = r.json().get("error", {})
    code = err.get("code")
    if code == "RATE_LIMITED":
        ...  # wait Retry-After, then retry
    elif code in ("INVALID_API_KEY", "DEVELOPER_ACCESS_REVOKED"):
        ...  # stop the bot and alert someone
    elif code == "CHAT_NOT_ALLOWED":
        ...  # skip this user
    else:
        raise RuntimeError(f"{r.status_code} {code}: {err.get('message')}")