الأخطاء والحدود
راجع كل حد ورمز خطأ في HUMAIN Voice، بما في ذلك جلسات Voice Agent، وأعد محاولة الطلبات الفاشلة دون تكرار العمل.
شكل استجابة الخطأ
تعيد مسارات HTTP جسم ErrorResponse. تصدر مسارات Socket.IO حدث error يحمل message بدلًا من error وdetail. اتخذ القرار من code وretryable، لا من نص الرسالة أبدًا.
| الحقل | HTTP | Socket.IO | المعنى |
|---|---|---|---|
code | نعم | نعم | رمز خطأ مقروء آليًا. |
retryable | نعم | نعم | هل يمكن أن تنجح إعادة محاولة هذا الطلب. |
timestamp | نعم | نعم | وقت الخادم عند الخطأ. |
data | نعم | نعم | عند رفض تجاوز الحد: limit وobserved وunit وbound. يحمل 429 في النسخ الدفعي { capacity } بدلًا منها. |
error، detail | نعم | لا | معرّف قديم ونص مقروء للبشر. |
message | 401 لمفتاح مفقود فقط | نعم (دائمًا) | نص مقروء للبشر. |
job_id / id | job_id | id | UUID المهمة أو التدفق. |
request_id | النسخ الدفعي | لا | معرّف تتبع لطلبات الدعم. |
retry_after_seconds | لا (ترويسة Retry-After) | نعم | الثواني المطلوب انتظارها قبل إعادة المحاولة. |
reason، retry_scope | لا | ASR_STREAM_EXPIRED فقط | سبب انتهاء التدفق؛ وقيمة retry_scope هي new_stream. |
يعيد ملف دفعي يتجاوز طوله بعد فك الترميز أربع ساعات ما يلي:
{
"error": "error.api.error.audio.duration_exceeded",
"code": "AUDIO_DURATION_EXCEEDED",
"detail": "error.api.error.audio.duration_exceeded",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": { "limit": 14400, "observed": 18000, "unit": "seconds", "bound": "audio_duration" }
}افحص حالة HTTP قبل تحليل جسم النجاح، واحتفظ بالجسم الخام إذا فشل تحليل JSON. على مسارات البث عبر HTTP، ينهي الفشل بعد بدء الخرج استجابة 200 بلا JSON للخطأ. في حزم SDK، تطلق استدعاءات النسخ الدفعي BatchTranscribeError بهذه الحقول. أما استدعاء TTS الفاشل فيحتفظ بالرسالة فقط، فاقرأ code وdata في دالة الاستدعاء onError / on_error.
سجّل code وحالة HTTP ومعرّف الطلب أو المهمة لكل خطأ. لا تسجّل مفاتيح API أو الصوت أبدًا.
الحدود
الحدود شاملة: الطلب الذي يساوي الحد تمامًا ينجح. يمكن للنشر ضبط قيم أخرى، فالقيمة data.limit في الخطأ هي المرجع. تسمي data.bound الحد الذي تم بلوغه.
النسخ الدفعي
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
| حجم الطلب، شاملًا مقاطع multipart | 512 MiB | 413 PAYLOAD_TOO_LARGE | request_bytes |
| ملفات الصوت لكل طلب | 1 | 422 FILE_COUNT_EXCEEDED | file_parts |
| أجزاء multipart لكل طلب | 8 | 422 FILE_COUNT_EXCEEDED | multipart_parts |
| مدة الصوت بعد فك الترميز | 4 h (14,400 s) | 422 AUDIO_DURATION_EXCEEDED | audio_duration |
| مدة معالجة تمييز المتحدثين، لكل النماذج | 2,097 s (34 min 57 s)، مع سقف 64 MiB للصوت بعد فك الترميز | يرفض العامل المعالجة بعد إنشاء المهمة | لا يوجد |
| سعة الصوت | بثواني الصوت | 429 RATE_LIMIT_EXCEEDED | لا يوجد؛ راجع data.capacity |
ينطبق سقف الأربع ساعات عند تقديم الطلب سواء فُعّل تمييز المتحدثين أم لم يُفعّل. يفرض عامل تمييز المتحدثين سقف المعالجة المنفصل بعد إنشاء المهمة. لا يضمن قبول الطلب اكتمال المعالجة؛ تحقّق من حالة المهمة. لا ينشئ الطلب المرفوض عند التقديم مهمة. إذا رُفض الطلب بعد بدء الرفع، فإنه يحتسب ثانية صوت واحدة (10 على الأكثر) من سعتك الدفعية. ولا تُحاسب عليها. يُرفض Content-Length المعلن الذي يتجاوز 512 MiB قبل احتساب أي شيء. أرسل جزء صوت واحدًا ولا شيء بعده؛ فالحمولة اللاحقة الكبيرة تعيد 413 مع unvalidatable_tail_bytes.
النسخ السريع
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
| حجم الرفع | 64 MiB | HTTP 413 PAYLOAD_TOO_LARGE. يصدر Socket.IO الخطأ ثم يقطع الاتصال. | fast_audio_bytes |
| مدة الصوت بعد فك الترميز | 1800 s (30 min) | HTTP 422 AUDIO_DURATION_EXCEEDED. يبقى Socket.IO متصلًا. | fast_audio_duration |
عبر HTTP، يغطي 64 MiB جسم multipart كله؛ وعبر Socket.IO، بايتات الوسائط فقط. الحدث audio_file_upload_success في Socket.IO إيصال: قد يتبعه خطأ في الصيغة أو المدة.
النسخ الفوري
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
| حجم الإطار، شاملًا الترويسة ذات 18 بايت | 16 MiB لكل حدث أو POST | 413 PAYLOAD_TOO_LARGE. يصدر Socket.IO الخطأ ثم يقطع الاتصال. | realtime_asr_frame_bytes |
| زمن خمول جلسة HTTP | 900 s | 408 SESSION_IDLE_TIMEOUT | session_idle |
| التدفقات المتزامنة | لكل حساب، وتحددها خطتك | 429 CONCURRENCY_LIMIT_EXCEEDED | account_concurrency_realtime_asr |
يشترك في التزامن كل مفاتيح API في الحساب، ولكل حمل عمل حصته الخاصة، فلا يتنافس النسخ الفوري وTTS.
تمييز المتحدثين المباشر
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
| حجم الإطار، شاملًا الترويسة | 16 MiB | 413 PAYLOAD_TOO_LARGE | realtime_diarization_frame_bytes |
| طلبات POST قيد التنفيذ عبر HTTP | 1 لكل UUID تدفق | قد تصل السجلات إلى استجابة خاطئة | لا يوجد |
تحويل النص إلى كلام
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
طول text | 500 نقطة رمزية (المجانية)، و1,000 (القياسية والمؤسسية) | 422 CHARACTER_COUNT_EXCEEDED | tts_input_characters |
| مراجع الصوت | 1 | 422 VOICE_REFERENCE_COUNT_EXCEEDED | tts_voice_reference_count |
| النص المنسوخ للمرجع | 500 نقطة رمزية | 422 CHARACTER_COUNT_EXCEEDED | tts_voice_reference_text_characters |
| حجم صوت المرجع بعد فك الترميز | 2 MiB | 413 PAYLOAD_TOO_LARGE | tts_voice_reference_bytes |
| مدة صوت المرجع | 15 s | 422 AUDIO_DURATION_EXCEEDED | tts_voice_reference_duration |
| جسم طلب HTTP | 16 MiB | 413 PAYLOAD_TOO_LARGE | لا يوجد |
| زمن التوليف | 25 s إجمالًا | 504 TTS_DEADLINE_EXCEEDED | لا يوجد |
| عمليات التوليف المتزامنة | لكل حساب، وتحددها خطتك | 429 CONCURRENCY_LIMIT_EXCEEDED | account_concurrency_tts |
النقاط الرمزية هي نقاط Unicode الرمزية، وتشمل المسافات في البداية والنهاية. تُفحص حدود TTS قبل أي خصم.
Voice Agent
| الحد | القيمة | عند التجاوز | data.bound |
|---|---|---|---|
| جسم طلب الجلسة | تحدده HUMAIN Voice؛ راجع data.limit | 413 PAYLOAD_TOO_LARGE | agent_request_bytes |
| أدوات العميل لكل جلسة | 16 | 400 VALIDATION_INVALID_PARAM | agent_client_tools |
| مهلة الانضمام بعد الطلب | نحو 60 s (expires_at) | تنتهي المكالمة بـuser_never_joined | لا يوجد |
| نتيجة أداة العميل | 15 KiB من JSON | يفشل استدعاء الأداة | لا يوجد |
| زمن تشغيل أداة العميل | 120 s | يفشل استدعاء الأداة | لا يوجد |
| المكالمات المتزامنة | لكل حساب، وتحددها خطتك | 429 CONCURRENCY_LIMIT_EXCEEDED | account_concurrency_agent |
| الدقائق اليومية | لكل حساب، وتحددها خطتك؛ وتتجدد عند 00:00 بتوقيت UTC | 429 RATE_LIMIT_EXCEEDED | agent_daily_minutes |
تنهي المدة القصوى للمكالمة وزمن الخمول مكالمةً جارية بالفعل؛ راجع الحدود والفوترة.
رموز الأخطاء
تستخدم أخطاء Socket.IO الرموز نفسها بلا حالة HTTP. يعني عمود إعادة المحاولة:
| إعادة المحاولة | المعنى |
|---|---|
| نعم | يمكن إعادة محاولة الطلب نفسه بأمان بعد تراجع. |
| بعد تعديل | أصلح الإدخال أو المفتاح أو الخطة أولًا. |
| تدفق جديد | ابدأ تدفقًا أو جلسة جديدة بـUUID جديد. |
| ليس تلقائيًا | ربما نجحت محاولة سابقة. |
| — | غير موثق؛ اتبع retryable في الخطأ. |
الرموز الشائعة
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
AUTH_UNAUTHORIZED | 401 | مفتاح API مفقود أو غير صالح. | أرسل x-api-key صالحًا. | بعد تعديل |
AUTH_FORBIDDEN | 403 | المفتاح لا يملك هذه الصلاحية. | استخدم مفتاحًا يملكها. | بعد تعديل |
METHOD_NOT_ALLOWED | 405 | طريقة HTTP خاطئة، أو الحدث المتقادم speaker_id. | أصلح المسار أو الحدث. | بعد تعديل |
VALIDATION_INVALID_FORMAT | 400 | جسم أو إطار أو WAV مرجعي مشوّه. | أصلح الترميز. | بعد تعديل |
VALIDATION_REQUIRED_FIELD | 400 | حقل مفقود، أو نص فارغ، أو بت بدء مفقود. | أضف الحقل. | بعد تعديل |
VALIDATION_INVALID_PARAM | 400 | معامل غير صالح أو محددا صوت معًا. | أصلح المعامل. | بعد تعديل |
VALIDATION_INVALID_UUID | 400 | معرّف مهمة أو voice_id مشوّه. | أرسل UUID صالحًا. | بعد تعديل |
VALIDATION_INVALID_LANGUAGE | 400 | لغة غير معروفة. | استخدم لغة مدرجة. | بعد تعديل |
VALIDATION_FILE_CORRUPT | 400؛ 422 في النسخ الدفعي | صوت تالف أو فارغ، أو إطار قصير. | أرسل صوتًا صالحًا. | بعد تعديل |
ASR_MODEL_NOT_FOUND | 400 | نموذج النسخ الدفعي أو السريع غير متاح. | اختر نموذجًا مدرجًا. | بعد تعديل |
PAYLOAD_TOO_LARGE | 413 | تجاوز حد بايتات (data.bound). | أرسل ملفات أو إطارات أصغر. | بعد تعديل |
AUDIO_DURATION_EXCEEDED | 422 | تجاوز حد مدة (data.bound). | قسّم الصوت. | بعد تعديل |
CREDITS_EXHAUSTED | 402 | نفد رصيد الحساب. | توقف وأضف رصيدًا. | بعد تعديل |
BILLING_AUTHORIZATION_UNAVAILABLE | 503 | تعذر على الفوترة الترخيص. | تراجع وأعد المحاولة. | نعم |
RATE_LIMIT_EXCEEDED | 429 | سعة النسخ الدفعي أو معدل الطلبات لكل مفتاح؛ وقد لا يكون جسم البوابة ErrorResponse. | أبطئ وتراجع. | نعم |
CONCURRENCY_LIMIT_EXCEEDED | 429 | عمليات كثيرة جدًا قيد التنفيذ. | انتظر Retry-After / retry_after_seconds. | نعم |
SERVER_INTERNAL | 500 | خطأ غير متوقع في الخادم، أو فشل البحث عن نتيجة النسخ الدفعي. | أعد محاولة قراءات النسخ الدفعي التي استخدمت save_result=true. | نعم |
يأتي 403 بلا جسم ErrorResponse من البوابة: افحص العنوان والمسار والترويسات.
رموز النسخ الدفعي
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
FILE_COUNT_EXCEEDED | 422 | ملفات أو أجزاء كثيرة جدًا. | أرسل ملفًا واحدًا. | بعد تعديل |
TRANSCRIPTION_JOB_NOT_FOUND | 404 | لا توجد مهمة بهذا UUID. | توقف عن الاستعلام؛ وافحص المعرّف المخزن. | بعد تعديل |
ASR_TRANSCRIPTION_FAILED | 500 | فشل الإرسال. | قد تكون المهمة موجودة؛ لا تعد الإرسال دون سياسة للتكرار. راجع واجهة REST للنسخ الدفعي. | ليس تلقائيًا |
رموز النسخ السريع والفوري والتمييز
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
ASR_UNSUPPORTED_CODEC | 400 | صوت النسخ السريع ليس AAC أو FLAC أو MP3 أو WAV أو MP4. | أعد ترميز الملف. | بعد تعديل |
ASR_TRANSCRIPTION_FAILED | 500 | فشل التعرف. | ابدأ تدفقًا جديدًا. | تدفق جديد |
ASR_STREAM_EXPIRED | لا يوجد | لا صوت خلال نافذة الخمول، أو فقد الخادم حالة التدفق (راجع reason). | ابدأ تدفقًا جديدًا. | تدفق جديد |
SESSION_BYTE_RATE_EXCEEDED | 429 | يصل الصوت أسرع من معدل الجلسة. | انتظر ثم أعد إرسال الحمولة نفسها (في API المباشرة؛ أما حزم SDK فتنهي التدفق). | نعم |
SESSION_SLOTS_EXHAUSTED | 429 | جلسات HTTP مفتوحة كثيرة جدًا. | أنهِ الجلسات ثم أعد المحاولة. | نعم |
SESSION_BYTES_EXCEEDED | 413 | أرسلت الجلسة بايتات كثيرة جدًا؛ الحد في data.limit. | ابدأ جلسة جديدة. | تدفق جديد |
SESSION_DURATION_EXCEEDED | 422 | الجلسة مفتوحة منذ وقت طويل؛ الحد في data.limit. | ابدأ جلسة جديدة. | تدفق جديد |
SESSION_IDLE_TIMEOUT | 408 | لا صوت خلال نافذة الخمول. | ابدأ جلسة جديدة. | تدفق جديد |
SESSION_EXPIRED | 409 | UUID لم يبدأ، أو انتهى، أو بدأ مرتين. | ابدأ جلسة جديدة. | تدفق جديد |
DIARIZATION_MODEL_NOT_FOUND | 400 | التمييز غير مضبوط. | تواصل مع الدعم. | بعد تعديل |
DIARIZATION_FAILED | 500 | فشل في السعة أو الاستدلال. | ابدأ تدفقًا جديدًا. | تدفق جديد |
رموز تحويل النص إلى كلام
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
CHARACTER_COUNT_EXCEEDED | 422 | النص أو النص المنسوخ للمرجع طويل جدًا. | قصّره إلى data.limit. | بعد تعديل |
VOICE_REFERENCE_COUNT_EXCEEDED | 422 | أكثر من مرجع واحد. | أرسل مرجعًا واحدًا. | بعد تعديل |
TTS_VOICE_NOT_FOUND | 400 | voice_id غير متاح. | اختر من قائمة الأصوات. | بعد تعديل |
TTS_INPUT_NOT_ALLOWED | 400 | رفضت سياسة المحتوى النص. | غيّر النص. | بعد تعديل |
TTS_MODERATION_UNAVAILABLE | 503 | تعذر على الإشراف أن يقرر. | تراجع وأعد المحاولة. | نعم |
TTS_EMOTION_MARKUP_INVALID | 400 | وسم <emotion …> غير سليم، أو مقطع غير مغلق، أو إغلاق لا يطابق (المشاعر وأسلوب الإلقاء). | أصلح الوسم عند الموضع المذكور في message. | بعد تعديل |
TTS_EMOTION_SEGMENT_COUNT_EXCEEDED | 400 | قسّمت الوسوم النص إلى أجزاء أكثر من data.limit. يصدر فقط في عمليات النشر التي تضبط حدودًا للمقاطع. | استخدم وسومًا أقل. | بعد تعديل |
TTS_EMOTION_SEGMENT_TOO_SHORT | 400 | جزء موسوم أقصر من data.limit حرفًا. يصدر فقط في عمليات النشر التي تضبط حدودًا للمقاطع. | أطِل الجزء أو احذف وسمه. | بعد تعديل |
SERVER_DEPENDENCY_FAILURE | 503 | انقطاع في التخزين أثناء حل voice_id. | تراجع وأعد المحاولة. | نعم |
TTS_VOICE_RESOLUTION_FAILED | 500 | بيانات الصوت المخزنة معطوبة. | اختر صوتًا آخر. | بعد تعديل |
TTS_SYNTHESIS_FAILED | 500 | فشل في النموذج أو السعة. | أعد المحاولة بـUUID جديد. | نعم |
TTS_DEADLINE_EXCEEDED | 504 | تجاوز التوليف 25 s. | تخلص من الصوت الجزئي وأعد المحاولة. | نعم |
BILLING_IDEMPOTENCY_CONFLICT | 409 | استُخدم UUID الطلب من قبل لنص مختلف، أو أُعيد استخدام الترويسة Idempotency-Key تحت طلب متغيّر دلاليًا (المدخلات كما هي، أو النموذج أو الصوت أو الصيغة بعد التطبيع؛ فإعادة الترتيب وحدها لا تغيّر)، أو وردت قيمة المفتاح نفسها من مفتاح API آخر للحساب نفسه، في POST /v1/audio/speech. | أرسل كل طلب مختلف بـUUID جديد أو بمفتاح Idempotency-Key جديد. | بعد تعديل |
رموز Voice Agent
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
VALIDATION_INVALID_PARAM | 400 | حقل غير معروف، أو قيمة غير صالحة، أو {{variable}} بلا قيمة؛ وكل مشكلة في data.errors. | أصلح الحقول المذكورة في path. | بعد تعديل |
AUTH_SCOPE_MISSING | 403 | المفتاح يفتقر إلى النطاق agent؛ وقيمة data.required_scope هي agent. | فعّل النطاق agent على المفتاح من لوحة التحكم. | بعد تعديل |
AUTH_FORBIDDEN | 403 | Voice Agent غير مفعّل للحساب خلال المرحلة التجريبية، أو معطّل. | تواصل مع الدعم. | بعد تعديل |
AGENT_SESSION_NOT_FOUND | 404 | GET /agent/sessions/{id} بمعرّف غير معروف أو بصيغة خاطئة، أو بجلسة تخص حسابًا آخر. | استخدم session_id من حسابك. | بعد تعديل |
CREDITS_EXHAUSTED | 402 | لا رصيد للدقيقة الأولى، أو الحساب ليس على الفوترة بالرصيد. | أضف رصيدًا، أو تواصل مع الدعم. | بعد تعديل |
CONCURRENCY_LIMIT_EXCEEDED | 429 | كل المكالمات المتزامنة في خطتك جارية؛ وقيمة data.bound هي account_concurrency_agent. | انتظر Retry-After، أو اطلب من المستخدم المحاولة بعد قليل. | نعم |
RATE_LIMIT_EXCEEDED | 429 | نفدت الدقائق اليومية في خطتك (data.bound هي agent_daily_minutes)، أو طلبات جلسات كثيرة جدًا من مفتاح واحد. | انتظر Retry-After. | نعم |
BILLING_AUTHORIZATION_UNAVAILABLE، SERVER_DEPENDENCY_FAILURE | 503 | الفوترة أو خدمة أخرى غير متاحة لوقت قصير. | تراجع وأعد المحاولة بقيمة Idempotency-Key نفسها. | نعم |
يُفحص طلب الجلسة بهذا الترتيب، ويُعاد أول فشل: المفتاح (401)، ثم النطاق agent (403)، ثم حجم الجسم (413)،
ثم الجسم (400)، ثم صلاحية الحساب (403 AUTH_FORBIDDEN)، ثم الرصيد (402)، ثم المكالمات المتزامنة (429)،
ثم الدقائق اليومية (429).
تُبلغ المكالمات التي تنتهي بعد بدئها عن سبب إنهاء بدل رمز خطأ.
رموز Socket.IO فقط ورموز النموذج المشتركة بين المسارات
| الرمز | HTTP | السبب | الإجراء | إعادة المحاولة |
|---|---|---|---|---|
RATE_LIMIT_SERVICE_BUSY | Socket.IO فقط | الخدمة مشغولة. | تراجع واتبع retryable. | — |
TTS_MODEL_NOT_FOUND | 400 | نموذج TTS غير متاح في هذا النشر، أو قيمة model قديمة (تتشارك واجهة Socket.IO وPOST /v1/audio/speech هذا الرمز). | اضبط model على مفتاح منشور (nebula). | بعد تعديل |
TTS_VOICE_LIST_FAILED | Socket.IO فقط | تعذر تحميل قائمة الأصوات. | اطلب القائمة مجددًا لاحقًا. | — |
قد يصل SERVER_INTERNAL وRATE_LIMIT_EXCEEDED أيضًا كأحداث Socket.IO.
إعادة المحاولة بأمان
أعد المحاولة فقط عندما تكون retryable هي true، وتكون العملية آمنة للتكرار، ويسمح موعدك النهائي. قيّد عدد المحاولات وكل تأخير وإجمالي زمن إعادة المحاولة، وأضف jitter.
- زمن الانتظار. التزم بـ
Retry-Afterأوretry_after_secondsعند وجودهما. وإلا استخدم تراجعًا أسيًا محدود السقف؛ ولا يضمن429في النسخ الدفعي وجودRetry-After. 429في النسخ الفوري وTTS. لا تستهلك هذه الرفوض رصيدًا أو حصة.- سعة النسخ الدفعي. القيمة
data.capacityفي429للنسخ الدفعي هي ثواني الصوت المتبقية؛ وقد تعني0أنه لا يوجد رصيد متاح. استخدمها لضبط وتيرة الإرسال، لا كزمن نوم. - إرسالات النسخ الدفعي. لا يوجد مفتاح idempotency، فبعد مهلة أو
500قد تكون المهمة موجودة. راجع واجهة REST للنسخ الدفعي. - قراءات نتيجة النسخ الدفعي. مرر
save_result=trueحتى لا تمسح استجابة ضائعة النتيجة. راجع واجهة REST للنسخ الدفعي. - التدفقات. لا يوجد استئناف أو إعادة تشغيل للإطارات. توقف عن الإرسال، واحتفظ بالنتائج المثبتة، وتخلص من المؤقتة، وأعد الاتصال بـUUID جديد.
- أخطاء الفوترة في منتصف التدفق طرفية: يرسل الخادم الخطأ ثم يقطع الاتصال. يُحاسب على الصوت المقبول قبلها.
يعيد هذا المثال محاولة قراءة نتيجة دفعية حتى خمس مرات مع تراجع وjitter:
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 keeps the stored result readable for a retry.
return await client.getResult(jobId, Language.ArEn, { saveResult: true });
} catch (error: unknown) {
let retryable: boolean;
let serverDelayMs = 0;
if (error instanceof BatchTranscribeError) {
retryable = error instanceof BatchTranscribeRateLimitError || error.retryable === true;
if (error instanceof BatchTranscribeRateLimitError && error.retryAfter !== undefined) {
serverDelayMs = error.retryAfter * 1_000;
}
console.error('error:', error.code ?? '', error.statusCode ?? '', error.capacity ?? '');
} else if (error instanceof TypeError) {
// fetch reports network failures as TypeError; a result read is safe to retry.
retryable = true;
console.error('error:', 'network', error.message);
} else {
throw error;
}
if (!retryable || attempt === attempts) throw error;
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'),
api_version: process.env.API_VERSION ?? 'v1',
});
try {
const result = await getResultWithRetry(client, jobId);
console.info('status:', result.status);
console.info(result.results?.transcript ?? '');
} finally {
await client.close();
}
}
void main().catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
مرر معرّف مهمة كوسيط أول. الخرج المتوقع (توضيحي):
error: SERVER_INTERNAL 500
status: done
Hello and welcome to the meeting.المهل
اضبط مهلة لكل طلب وموعدًا نهائيًا إجماليًا لسير العمل. تعني مهلة الطلب أن عميلك توقف عن الانتظار، لا أن الخادم توقف. يغطي الموعد النهائي الإجمالي الاتصال والعمل وإعادة المحاولات والتنظيف؛ وعند انقضائه توقف.
للخادم مواعيده النهائية الخاصة: ينتهي توليف TTS بعد 25 s إجمالًا أو 60 s بلا تقدم، وتنتهي جلسة HTTP بعد 900 s من الخمول. بعد وصول أول مقطع صوت إلى الاستدلال، ينتهي أيضًا تدفق ASR غير المكتمل بعد 60 s من دون تمرير مقطع صوت آخر. لا تعيد استجابات الاستدلال ضبط هذه المهلة. إغلاق استجابة البث عبر HTTP بعد نحو ثانيتين أمر طبيعي ولا يُنهي الجلسة.
نظّف في finally. يلغي قطع اتصال TTS عبر Socket.IO الطلبات الجارية لذلك الاتصال، ولا يرسل الخادم لها صوتًا أو أخطاء بعد ذلك. ويلغي إلغاء طلب TTS عبر HTTP توليفه. مهل SDK الافتراضية في صفحتي SDK لـJavaScript وPython.