الأخطاء
كل رموز أخطاء Direct API ومعانيها، وهل تعيد المحاولة، بما في ذلك ما تفعله بعد فشل استدعاء مدفوع بخطأ 5xx.
لكل خطأ الجسم نفسه. افرّع منطقك بناءً على حالة HTTP وcode؛ واعرض description أو error.message على الأشخاص.
{
"description": "Human-readable explanation, safe to log.",
"code": "machine_readable_code",
"data": { "request_id": "…", "…": "…" },
"error": { "error_code": "…", "message": "…" }
}تحمل كل استجابة، ناجحة كانت أو خطأ، X-Request-Id. أدرجه عند تواصلك مع الدعم.
رموز الأخطاء
| HTTP | code | المعنى | إعادة المحاولة |
|---|---|---|---|
| 400 | invalid_request | JSON مشوّه، أو حقل غير معروف في الجسم، أو فشل input في مخطط الأداة (مع تسمية كل حقل خاطئ) | لا، أصلح الطلب |
| 401 | invalid_api_key | مفتاح مفقود أو مشوّه أو ملغى أو منتهي الصلاحية | لا |
| 402 | insufficient_credits | لا تستطيع المؤسسة دفع تكلفة الاستدعاء | بعد شحن الرصيد |
| 402 | api_key_credit_limit_reached | سيتجاوز الاستدعاء الحد اليومي أو الشهري أو الإجمالي للمفتاح (يوضح data.period أيها) | بعد إعادة ضبط النافذة أو رفع الحد |
| 402 | subscription_paused | اشتراك المؤسسة متوقف مؤقتًا | بعد استئنافه |
| 402 | payment_required | اشتراك المؤسسة متأخر السداد | بعد إتمام الدفع |
| 403 | direct_api_disabled | Direct API غير مفعّلة لهذه المؤسسة | لا، تواصل مع Morphic |
| 403 | insufficient_scope | يفتقر المفتاح إلى النطاق الذي تحتاجه هذه الأداة (data.required_scopes) | لا، استخدم مفتاحًا آخر |
| 403 | plan_upgrade_required | النموذج أو الميزة غير متاحين في خطتك | لا |
| 403 | tool_not_available | الأداة تخصم أرصدة والأدوات المدفوعة لم تُفعَّل لمؤسستك بعد (يذكرها data.tool)؛ وتفعّلها جهة الاتصال الخاصة بك في Morphic | لا |
| 403 | model_disabled_by_organization | أوقف أحد مسؤولي المؤسسة هذا النموذج أو الدقة أو خيار الصوت ولم يسمح به لـ API | لا، اسأل المسؤول لديك |
| 404 | not_found | أداة أو عملية توليد أو ويبهوك غير معروفة، أو خارج نطاق وصول هذا المفتاح | لا |
| 409 | idempotency_conflict | أُعيد استخدام Idempotency-Key مع جسم أو أداة مختلفة | لا، استخدم مفتاحًا جديدًا |
| 409 | idempotency_in_progress | الطلب الأصلي بهذا المفتاح ما زال قيد التنفيذ | نعم، بعد ثانية |
| 409 | idempotency_outcome_unknown | الطلب الأصلي بمفتاح Idempotency-Key هذا فشل أو لم يُجب قط بعد أن ربما نُفِّذ، لذا نتيجته مجهولة | لا: تحقق من نتيجته، ثم استخدم مفتاحًا جديدًا |
| 413 | payload_too_large | الجسم يتجاوز 1 MB | لا |
| 422 | tool_refused | الإدخال سليم الصيغة لكن لا يمكن تشغيله؛ ولم يُخصم شيء | لا، غيّر الإدخال |
| 429 | rate_limited | بُلغ حد المعدل | نعم، بعد Retry-After |
| 500 | internal_error | خطأ من جانبنا | الاستدعاء المجاني: نعم؛ الاستدعاء المدفوع: راجع ما يلي |
| 503 | service_unavailable | ضغط مؤقت أو صيانة | الاستدعاء المجاني: نعم، مع التراجع التدريجي؛ الاستدعاء المدفوع: راجع ما يلي |
| 504 | tool_timed_out | لم تُجب الأداة خلال 60 ثانية؛ والاستدعاء الذي يبدأ عمليات توليد ربما يكون قد بدأها | الاستدعاء المجاني: نعم؛ الاستدعاء المدفوع: راجع ما يلي |
يذكر 422 tool_refused الحقل والقيمة والقيم التي كانت ستنجح؛ راجع رفض الأداة. وعملية التوليد التي تفشل بعد بدئها تُبلغ بـ error.error_code الخاص بها في كائن عملية التوليد، ويُسترد المبلغ المخصوم منها.
الاستدعاءات المدفوعة التي تُجيب بـ 5xx
الاستدعاء المدفوع الذي يُجيب بـ 500 أو 503 أو 504 ربما بدأ العمل وخصم مقابله قبل أن يفشل. وإعادة محاولته بمفتاح Idempotency-Key نفسه لا تنفّذه مرتين أبدًا: إذ تُجيب إعادة المحاولة بـ 409 idempotency_outcome_unknown.
- تحقق مما فعله الاستدعاء:
list_generations، أوGET /v1/direct/usageمع التصفية حسب الوقت. - أرسل
Idempotency-Keyجديدًا فقط للعمل الذي لم يبدأ.
عندما لا تصل أي إجابة على الإطلاق (اتصال منقطع)، أعد المحاولة بالمفتاح نفسه. ستحصل على الإجابة المخزنة، أو على 409 idempotency_in_progress ما دام لا يزال قيد التنفيذ. راجع التكرار الآمن.
إذا واجهت أي مشكلة أو كانت لديك أي أسئلة، فلا تتردد في التواصل معنا. يسعدنا مساعدتك. اكتب لنا على support@morphic.com.