الأخطاء وحدود المعدل

عند أي فشل، احتفظ أولاً بالإشارة، وأوقف العمل المتأثر، وحدد هل النتيجة معلومة. لا تعد المحاولة إلا عندما تكون العملية آمنة للتكرار، وتسمح الحالة المنظمة بذلك، وتبقى مهلة للتطبيق.

1. صنّف موضع ظهور الفشل

غياب الاستجابة ليس مساويًا لـretryable: true. كما أن retryable: true المنظمة لا تكفي وحدها؛ فقد يظل تكرار الرفع أو البث المنقطع غير آمن أو ملتبسًا.

2. احتفظ بحقول HTTP وSDK

تستخدم عمليات Batch REST وHTTP المباشر المحمية شكل HTTP المسمى ErrorResponse:

يعني مثال Batch المتحقق منه هذا «صحح الجسم متعدد الأجزاء ولا تعده من دون تغيير»:

{
  "error": "error.api.error.multipart.file.missing",
  "code": "VALIDATION_REQUIRED_FIELD",
  "detail": "error.api.error.multipart.file.missing",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

تحقق دائمًا من حالة HTTP قبل اختيار محلل النجاح. احتفظ بالجسم الخام عندما يفشل التحليل المنظم.

يعرض SDK 0.18.0 إسقاطات مختلفة:

استمر في التحقق من دخل TTS قبل الإرسال، ومرّر دائمًا مهلة صريحة (timeoutSeconds في JavaScript وtimeout_seconds في Python). اقرأ code وdata من استدعاء الخطأ العام قبل رفض الطلب؛ فالاستثناء العام يحتفظ بالرسالة فقط.

3. طبّق جدول القرار

قد تعيد بوابة النشر 429 لطلب Realtime HTTP، بينما قد تطوي خلفية Fast أو البث الحي الحالية فشل سعة الصوت الداخلي إلى 500 قابلة للإعادة مع ASR_TRANSCRIPTION_FAILED. لا تستنتج حصة Realtime أو مجموعة سعة أو نافذة إعادة ضبط من أي من الاستجابتين أو من سعة Batch.

4. عامل Batch 429 كضغط سعة

يتضمن 429 في Batch الحقول المنظمة المعتادة إضافة إلى data.capacity:

{
  "error": "error.rate_limit",
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "error.rate_limit",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "capacity": 120.5 }
}

capacity هي السعة المتبقية مقاسة بثواني الصوت. استخدمها لقرارات الطابور والقبول. وهي ليست حصة موثقة أو نافذة إعادة ضبط أو عدد ثوانٍ للانتظار.

لا يَعِد عقد OpenAPI بترويسة Retry-After. لا تُملأ retryAfter / retry_after في SDK إلا عندما توجد ترويسة صالحة فعلاً. عند غيابها، طبق تراجعًا أسيًا محدودًا مع jitter. قيّد دائمًا المحاولات، وكل تأخير، وزمن إعادة المحاولة الكلي، وتزامن المنتجين بمهلة كلية.

5. احفظ نتيجة Batch قبل إعادة قراءتها

لا يعيد SDK المنشور محاولات Batch. الخيار maxRetries / max_retries مهمل ومتجاهل ومحتفظ به للتوافق فقط. تعيد هذه الأمثلة المختبرة getResult() / get_result()، لا الرفع، وتمرر صراحة saveResult: true / save_result=True. قد تمسح القيمة الافتراضية false النتيجة النهائية بعد بناء الاستجابة، ولذلك قد تتبع الاستجابة المفقودة حالة cleared. يتيح خيار الحفظ إعادة محدودة لكنه لا يحدد مدة احتفاظ. تستخدم الأمثلة الخصائص ذات النوع المنشورة:

import {
  BatchTranscribeClient,
  BatchTranscribeError,
  BatchTranscribeRateLimitError,
  Language,
  type TranscriptionResponse,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function getResultWithRetry(
  client: BatchTranscribeClient,
  jobId: string,
  attempts = 5,
): Promise<TranscriptionResponse> {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      // saveResult prevents a terminal read from clearing the stored result
      // before a retry. It does not establish a retention duration.
      return await client.getResult(jobId, Language.ArEn, { saveResult: true });
    } catch (error: unknown) {
      if (!(error instanceof BatchTranscribeError)) throw error;

      const rateLimited = error instanceof BatchTranscribeRateLimitError;
      const retryable = rateLimited || error.retryable === true;
      console.error({
        statusCode: error.statusCode,
        code: error.code,
        capacity: error.capacity,
      });
      if (!retryable || attempt === attempts) throw error;

      const serverDelayMs = rateLimited && error.retryAfter !== undefined
        ? error.retryAfter * 1_000
        : 0;
      const exponentialDelayMs = 500 * 2 ** (attempt - 1);
      await pause(Math.max(serverDelayMs, exponentialDelayMs) + Math.random() * 250);
    }
  }

  throw new Error('Retry loop exhausted');
}

async function main(): Promise<void> {
  const jobId = process.argv[2];
  if (!jobId) throw new Error('Pass a batch job ID as the first argument');

  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
  });
  try {
    const result = await getResultWithRetry(client, jobId);
    console.info(result.status, result.results?.transcript ?? '');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

السلوك المتوقع: تستخدم القراءات القابلة للإعادة خمس محاولات على الأكثر، وتحترم قيمة retryAfter / retry_after فعلية عند وجودها، وتضيف تأخيرًا أسيًا وjitter، وتعيد إطلاق الفشل النهائي. لا يغني حد المحاولات عن مهلة كلية للتطبيق.

6. أبقِ العمليات الملتبسة خارج الإعادة الآلية

رفع الملفات الكاملة

لا يوثق إنشاء عمل Batch وإرسال الصوت الكامل عبر Fast عقد مفتاح idempotency. لا تثبت المهلة أو الانقطاع بعد إرسال البايتات النجاح أو الفشل؛ فقد يكون الخادم قبل الطلب.

إذا عاد jobId أو UUID للطلب، فاحتفظ به وتابع مسار النتيجة المعتاد لتلك العملية. ومن دون استجابة حاسمة، سجل المحاولة الملتبسة ولا تكرر إلا وفق سياسة تطبيق تقبل صراحة العمل المكرر.

بث Realtime

لا تعرّف عقود Socket.IO وHTTP العامة استئنافًا شفافًا ولا إعادة idempotent للإطارات. عند خطأ أو انقطاع:

1. أوقف إرسال الصوت وأغلق البث أو الاستجابة القديمة.
2. احتفظ بالنتائج المثبتة وتجاهل الحالة المؤقتة غير المحسومة.
3. سجل فترة الصوت الملتبسة.
4. أعد الاتصال بتراجع محدود وUUID جديد فقط إذا سمح الخطأ ومهلة التطبيق.
5. افصل البث الجديد حتى يوفق التطبيق الخطين الزمنيين صراحة.

لا تعد الإطارات القديمة أو تستخدم UUID القديم بافتراض إزالة الخادم لتكرارها.

7. افصل المهل عن المهلة الكلية

تكون قيمة timeoutSeconds في TTS لـJavaScript افتراضيًا 30 ثانية من الخمول أثناء انتظار كل مقطع صوت. لا يضع TTS في Python مهلة ما لم تمرر timeout_seconds. ينتظر close() في Realtime ASR SDK ‏is_final على مستوى البروتوكول أو خطأ موجهًا أو مهلة الإغلاق فقط، ويمكنه العودة عند انتهاء ذلك الانتظار. لا يغني أي من هذه الضوابط عن المهلة الكلية.

بعد أي انتهاء، نظف داخل finally: ألغِ قراءات HTTP وأغلق أجسام الاستجابة؛ وأوقف صوت Socket.IO واستدعِ disconnect() أو اخرج من سياق Python غير المتزامن؛ وأغلق عميل Batch. لا تستنتج أن تنظيف العميل ألغى العمل على الخادم. ولا تستنتج أنه ألغى توليف TTS جارٍ.

8. سجل القرارات واختبر مسارات الفشل

سجل العملية، ووسيلة النقل، وحالة HTTP أو اسم الحدث، وcode، وقرار إعادة المحاولة، وUUID للطلب أو العمل، ورقم المحاولة، والمهلة المتبقية، ونوع المهلة، وسعة Batch عند وجودها. لا تسجل مفاتيح API أو الصوت الكامل أو نصًا حساسًا افتراضيًا.

بعد ذلك، شغّل مثال القراءة الآمنة، ثم اختبر الدخل غير الصالح، والمصادقة، و429 الصريح، ومهلة القراءة، ومهلة رفع ملتبسة، وانقطاع Realtime، وانتهاء انتظار النتيجة النهائية، والتنظيف في بيئة اختبار معزولة.