أخطاء GraphQL

​

أخطاء المُحلِّل تصل مع HTTP 200

// WRONG - will treat a failed request as a success
if (response.ok) {
  return "everything worked";
}

if (!response.headers.get("content-type")?.includes("json")) {
  throw new Error(`GraphQL request failed with HTTP ${response.status}`);
}

const result = await response.json();

if (result.errors) {
  for (const error of result.errors) {
    // Errors caught before execution have no extensions, so read it safely.
    console.log(error.message, error.extensions?.status);
  }
}

• يُرجع الطلب غير الصحيح حالة خطأ: HTTP 400 لـ JSON غير صالح أو غياب query، و413 لجسم يتجاوز 64 KB، و405 لطريقة غير POST، و415 لـ Content-Type غير مدعوم.
• يُرجع الاستعلام غير الصالح وفقًا للمخطط HTTP 400 فقط إذا أرسل طلبك Accept: application/graphql-response+json. ويشمل ذلك خطأ الصياغة، والحقل غير المعروف، ونوع الوسيط الخاطئ، وقيمة التعداد غير الصالحة، والاستعلام الذي يتجاوز حدود الاستعلام. إذا أرسلت Accept: application/json، أو لم ترسل ترويسة Accept، فإن الخطأ نفسه يُرجع HTTP 200. وفي كلتا الحالتين، يحتوي الجسم على مصفوفة errors دون data.

​

شكل الخطأ

{
  "data": { "postHistory": null },
  "errors": [
    {
      "message": "Rate limit exceeded",
      "path": ["postHistory"],
      "extensions": {
        "status": 429,
        "retryAfter": 7
      }
    }
  ]
}

• message: وصف مقروء للبشر. نُزيل مفاتيح API وبيانات الاعتماد الأخرى من رسائل أخطاء المُحلِّل، لكن الخطأ المتعلق بقيمة أرسلتها، مثل متغير من نوع خاطئ، قد يكرر تلك القيمة. تعامل مع message على أنها قد تكون حساسة قبل تسجيلها.
• path: الحقل الذي فشل في استعلامك. عند وجود عدة حقول في طلب واحد، هذه هي الطريقة لمعرفة أيّها فشل.
• extensions.status: حالة HTTP التي كان سيُرجعها استدعاء REST المكافئ. اعتمد على هذه القيمة في التفرّع.
• extensions.code: رمز خطأ Ayrshare الرقمي، عندما توفّره نقطة النهاية الأساسية.
• extensions.retryAfter: يظهر في استجابات 429 الخاصة بالحصة أو حدود المعدل في الخدمات الأصلية عندما يتوفر تأخير لإعادة المحاولة. ولا يظهر في استجابة 429 الخاصة بميزانية الإرسال لكل طلب.

​

النجاح الجزئي

{
  history: postHistory(lastDays: 7)
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}

{
  "data": {
    "history": { "history": [{ "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }], "refId": "9d2a7c41f0b8e6d35a1c", "count": 1, "lastUpdated": "2026-09-24T12:00:00.000Z", "nextUpdate": "2026-09-24T12:00:00.000Z" },
    "analytics": null
  },
  "errors": [
    {
      "message": "Rate limit exceeded",
      "path": ["analytics"],
      "extensions": { "status": 429 }
    }
  ]
}

​

النجاح الجزئي في المنشورات متعددة الشبكات

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [FACEBOOK, INSTAGRAM]
    idempotencyKey: "multi-network-hi-001"
  }) {
    status
    postIds { platform postUrl }
    errors { platform message code }
    blocked { platform message }
  }
}

• postIds: الشبكات التي تم النشر عليها، مع عناوين URL لمنشوراتها. حالات النجاح فقط.
• errors: الشبكات التي فشل النشر عليها، مع السبب.
• blocked: الشبكات التي أُوقفت قبل أي محاولة، على سبيل المثال بواسطة قاطع الدائرة الخاص بكل شبكة بعد حالات فشل حتمية متكررة. وهي منفصلة عن محاولات المزوّد التي أرجعت أخطاء.

​

إعادة المحاولة

​

الحالات الشائعة