الأخطاء

تسرد هذه الصفحة كل خطأ تعيده نقاط النهاية في /v1: رمز HTTP، وerrorMessage بالنص الحرفي، والشرط الذي يطلقه، والإصلاح. وهي للمهندس الذي يكتب فرع معالجة الأخطاء في عميله. أما أخطاء المهام غير المتزامنة، فليست أخطاء HTTP، وهي في آخر الصفحة.

شكل استجابة الخطأ

كل خطأ كائن JSON واحد، يحمل الحقول الأربعة نفسها التي تحملها الاستجابة الناجحة. قيمة success هي false، وقيمة data هي null، وstatusCode يكرر رمز HTTP، وerrorMessage هو النص المقتبس في الجداول أدناه. يحمل كل خطأ على مسار /v1 أيضًا الحقل docs، وهو رابط إلى هذه الصفحة. أما 401 فيرتبط بصفحة المصادقة بدلًا منها.

{
  "data": null,
  "statusCode": 400,
  "success": false,
  "errorMessage": "text must be shorter than or equal to 500 characters",
  "docs": "https://echonova.ai/docs/developers/errors"
}

عندما تفشل عدة قواعد تحقق في طلب واحد، تُدمج رسائلها في errorMessage واحد، مفصولة بفاصلة ومسافة. طابق الرمز أولًا، ثم الرسالة. الرسالة نص عادي وليست رمزًا، وأي تغيير فيها مذكور في سجل التغييرات.

المصادقة

يُرفض الطلب قبل تشغيل نقطة النهاية. كل 401 يحمل الرسالة نفسها، فلا يخبرك النص أي الأسباب الخمسة هو السبب. ترتيب الفحوص كاملًا في المصادقة.

حد معدل الطلبات وحد الرصيد والرصيد

يعيد خطآن مختلفان الرمز 429. اقرأ errorMessage قبل إعادة المحاولة: أحدهما يزول مع الوقت، والآخر لا يزول.

التحقق من الطلب

يرفض التحقق من الجسم أو المعاملات هذه الأخطاء قبل تنفيذ أي عمل. لا يُحتسب أي رصيد. تُقصّ المسافات البيضاء في بداية كل نص ونهايته قبل فحص هذه القواعد، وتُرفض الحقول غير المعرّفة.

الرفع

تُطلق هذه الأخطاء على POST /v1/speech-to-text وPOST /v1/speech-to-text/sync وPOST /v1/sound-cleaning أثناء استلام الملف أو فحصه. لا يُحتسب أي رصيد. ينطبق صفوف language وnumbers_as_digits وidentify_speakers على نقطتي تحويل الكلام إلى نص فقط.

تنقية الصوت

تُطلق هذه الأخطاء على POST /v1/sound-cleaning، إضافةً إلى أخطاء الرفع أعلاه.

غير موجود

تأتي الرسائل الثلاث 404 نفسها من GET وDELETE على المهمة، وتأتي STT Job not found أيضًا من تنزيلها. يحذف المفتاح مهام API في مساحة عمله، أيًّا كان المفتاح الذي أنشأها، فالمهمة التي تخص مساحة عمل أخرى ترد 404.

حذف المهام

تُطلق هذه الأخطاء على DELETE /v1/text-to-speech/jobs/{jobId}، وDELETE /v1/speech-to-text/jobs/{jobId}، وDELETE /v1/sound-cleaning/jobs/{jobId}.

تنزيل النصوص المفرّغة

تُطلق هذه الأخطاء على GET /v1/speech-to-text/jobs/{jobId}/export، إضافةً إلى أخطاء المصادقة وحد معدل الطلبات والخدمة، وInvalid identifier، وproperty <name> should not exist، وSTT Job not found أعلاه. لا يُحتسب أي رصيد مقابل التنزيل. النجاح هو الملف نفسه، أما الخطأ فهو كائن الخطأ المعتاد.

تذاكر الودجت

تظهر عند استدعاء POST /v1/widgets/{publicId}/tickets. إصدار التذكرة مجاني. لا يُخصم أي رصيد.

أخطاء الخدمة

تُطلق أثناء بدء التوليد والتفريغ النصي، سواء في الاستدعاءات المتزامنة أو عند بدء الاستدعاءات غير المتزامنة. عندما لا تُقبل العملية، يُسترد الرصيد المحتسب، ويفشل الطلب بأحد هذه الأخطاء.

أخفاق المهام غير المتزامنة

لا تعيد المهمة غير المتزامنة التي تفشل بعد قبولها خطأ HTTP. تصبح status للمهمة failed، ويحمل حقل error السبب، ويُسترد الرصيد، وتُرسَل في معظم الحالات Webhook باسم job.failed. ويحتفظ creditsConsumed بالمبلغ الذي حُسب.

لا ترسل المهلة أي Webhook، فالعميل الذي ينتظر job.completed أو job.failed فقط لن يعرف عنها أبدًا. استخدم الاستعلام الدوري عبر GET /v1/text-to-speech/jobs/{jobId} أو GET /v1/speech-to-text/jobs/{jobId} إذا لم يصل أي حدث بعد 15 دقيقة من POST. أجسام الأحداث موجودة في أحداث Webhook.

نماذج الكود

اقرأ الحالة، ثم errorMessage. أعد المحاولة فقط عند 429 الخاص بحد معدل الطلبات، بعد ثواني Retry-After، وعند الأخطاء 503 و504. أي إعادة محاولة تُنشئ مهمة ثانية مذكورة في أعد المحاولة بأمان.

curl -s -o response.json -w "%{http_code}" \
  -X POST "https://api.echonova.ai/v1/text-to-speech/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "", "voiceId": "VOICE_ID"}'
# prints 400; response.json holds "text must be longer than or equal to 1 characters, text should not be empty"

import time
import requests

response = requests.post(
    "https://api.echonova.ai/v1/text-to-speech/sync",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "", "voiceId": "VOICE_ID"},
)
body = response.json()
if not body["success"]:
    message = body["errorMessage"]
    if response.status_code == 429 and "Retry-After" in response.headers:
        time.sleep(int(response.headers["Retry-After"]))
        # retry the request
    elif response.status_code in (503, 504):
        time.sleep(5)
        # retry the request
    else:
        raise RuntimeError(f"{response.status_code}: {message}")

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/sync', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: '', voiceId: 'VOICE_ID' }),
});
const body = await response.json();
if (!body.success) {
  const retryAfter = response.headers.get('Retry-After');
  if (response.status === 429 && retryAfter) {
    await new Promise((r) => setTimeout(r, Number(retryAfter) * 1000));
    // retry the request
  } else if (response.status === 503 || response.status === 504) {
    await new Promise((r) => setTimeout(r, 5000));
    // retry the request
  } else {
    throw new Error(`${response.status}: ${body.errorMessage}`);
  }
}

الأسئلة الشائعة

أي الأخطاء آمن لإعادة المحاولة؟

الرمز 429 الخاص بحد معدل الطلبات، بعد ثواني Retry-After، وكل 503 و504. أما 400 و401 و403 و404 و402 فتعيد الجواب نفسه حتى تغيّر الطلب أو المفتاح أو الرصيد. أي إعادة محاولة تُنشئ مهمة ثانية مذكورة في أعد المحاولة بأمان.

هل يُحتسب شيء عند ظهور خطأ؟

لا. كل خطأ مذكور أعلاه يُطلق قبل الاحتساب، أو يُسترد الرصيد قبل إعادة الخطأ.

لماذا يوجد استجابتان بالرمز 429؟

الأولى لحد معدل الطلبات، وتزول مع الوقت، وتحمل Retry-After. والثانية هي حد الرصيد للمفتاح، ولا تزول إلا عندما ترفع الحد أو تبدأ دورة الفوترة التالية، ولا تحمل أي header. فرّق بينهما من خلال errorMessage.

لماذا تقول كل استجابة 401 الشيء نفسه؟

تغطي Unauthorized header مفقودًا أو مشوّهًا، ومفتاحًا غير معروف، ومفتاحًا محذوفًا، ومفتاحًا معطّلًا، وحسابًا مغلقًا. تحقّق من header أولًا، ثم من الحالة للمفتاح تحت المطورون، ثم مفاتيح واجهة برمجة التطبيقات.

هل أطابق errorMessage في الكود؟

نعم، بعد مطابقة الرمز أولًا. الرسائل نص عادي، وأي تغيير فيها مذكور في سجل التغييرات.

صفحات ذات صلة

• المصادقة
• حد معدل الطلبات
• الرصيد
• أصوات تحويل النص إلى كلام وخياراته
• تنسيقات تحويل الكلام إلى نص ومخرجاته
• أحداث Webhook
• أعد المحاولة بأمان
• اقرأ سجل الطلبات