Skip to main content
يعرض الـ SDK فئتَي أخطاء: YoukaRequestError لأخطاء HTTP وإخفاقات التحقق من الصحة، وYoukaTaskError للمهام غير المتزامنة التي انتهت بحالة غير ناجحة. كلتاهما تمتدان Error وتحملان حقولًا منظَّمة بحيث يمكنك التفريع بناءً على code وstatus وقابلية إعادة المحاولة.

​
YoukaRequestError

يتم طرحه عند أخطاء HTTP، وإخفاقات التحقق من صحة الطلب، والاستجابات غير السليمة. 
import { YoukaRequestError } from "@youka/sdk";

try {
  await client.projects.create(body);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      retryable: error.retryable,
      details: error.details,
    });
  } else {
    throw error;
  }
}

​
الحقول

​
code
string
رمز خطأ قابل للقراءة آليًا، مثل INVALID_REQUEST وUNAUTHORIZED و UPLOAD_FAILED.
​
message
string
وصف قابل للقراءة البشرية.
​
status
number
رمز حالة HTTP، إن كان متاحًا.
​
retryable
boolean
true إذا اعتبر الـ SDK أن الخطأ يستحق إعادة المحاولة (حدود المعدّل، أخطاء خادم عابرة، إعادة تشغيل idempotent قيد التقدم).
​
details
unknown
تفاصيل مقدّمة من الخادم، وعادةً ما تكون قائمة مشكلات Zod لأخطاء التحقق من الصحة.

​
أكواد شائعة

الرمزالسببقابل لإعادة المحاولة؟
INVALID_REQUESTفشل جسم الطلب في التحقق من مخططه قبل إرساله.No
UNAUTHORIZEDمفتاح API مفقود أو غير صالح.No
NOT_FOUNDالمورد غير موجود أو أنك تفتقر إلى صلاحية الوصول.No
CONFLICTتعارض في الإصدارات (HTTP 409).Yes
TOO_MANY_REQUESTSتم الوصول إلى حد المعدّل (HTTP 429).Yes
INTERNAL_SERVER_ERRORعطل خادم عابر (HTTP 500).Yes
IDEMPOTENT_REPLAY_IN_PROGRESSالطلب الأصلي ما يزال قيد التنفيذ تحت نفس مفتاح idempotency (HTTP 202).Yes
INVALID_RESPONSEأعاد الخادم جسمًا لا يطابق المخطط المتوقع.No
UPLOAD_FAILEDأعادت عملية رفع Signed URL حالة غير 2xx.Depends on status

​
YoukaTaskError

يتم طرحه من client.tasks.wait(...) وclient.projects.wait(...) وclient.exports.wait(...) عندما تنتهي المهمة أو عملية التصدير الأساسية بحالة failed أو cancelled أو timed-out. 
import { YoukaTaskError } from "@youka/sdk";

try {
  await client.projects.wait(created);
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      task: error.task,
    });
  } else {
    throw error;
  }
}

​
الحقول

​
code
'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
يرتبط مباشرةً بالحالة النهائية للمهمة.
​
message
string
إما رسالة خطأ المهمة المقدّمة من الخادم أو بديل مُنشأ تلقائيًا.
​
status
TaskStatus
الحالة النهائية للمهمة.
​
task
RestTask
الحمولة الكاملة للمهمة في لحظة الفشل. مفيدة للتسجيل ورسائل الأخطاء الموجّهة للمستخدم.

​
نمط إعادة المحاولة

ادمج retryable مع مفتاح idempotency لبناء حلقة إعادة محاولة آمنة: 
import { YoukaRequestError } from "@youka/sdk";

async function createWithRetry<T>(fn: () => Promise<T>, maxAttempts = 3) {
  let lastError: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      if (
        error instanceof YoukaRequestError &&
        error.retryable &&
        attempt < maxAttempts
      ) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1_000));
        continue;
      }
      throw error;
    }
  }

  throw lastError;
}

await createWithRetry(() =>
  client.projects.create(body, {
    idempotencyKey: "import-2026-04-08-song-001",
  }),
);
احرص دائمًا على إعادة استخدام نفس مفتاح idempotency عبر محاولات الإعادة. وإلا فسيتعامل الخادم مع الإعادة كطلب جديد وقد ينتهي بك الأمر إلى تكرارات.

​
الإيقاف والإلغاء

إن إيقاف الطلب (Abort) يطرح AbortError القياسي — وليس YoukaRequestError. تحقّق منه صراحةً: 
try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Cancelled by user");
    return;
  }
  throw error;
}

​
ما التالي

  • المهام — مساعدات الانتظار واستطلاع المهام المتقدم
  • المصادقة — خيارات المُنشئ والإشارات
  • أخطاء API — نفس الأكواد في HTTP الخام