تعامل مع رموز أخطاء Rivya API العامة، وقيم حالة HTTP، وحدود المعدل، وتعارضات idempotency، وقرارات إعادة المحاولة.

تعيد Rivya API رموز أخطاء عامة مستقرة بصيغة JSON. تعامل مع قيمة error.code باعتبارها عقد التكامل.

شكل الخطأ

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

احتفظ بـ requestId في سجلاتك عندما تطلب من دعم Rivya التحقيق في طلب API فاشل.

رموز الأخطاء المستقرة

Code	HTTP status	المعنى	الإجراء المقترح
`public_api_disabled`	503	استدعاءات Public API معطلة مؤقتا.	أعد المحاولة لاحقا أو استخدم Studio يدويا.
`api_key_missing`	401	لم يتضمن الطلب مفتاح Bearer API.	أرسل `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	لا يمكن التحقق من المفتاح.	تحقق من المفتاح ودوّره إذا لزم الأمر.
`api_key_revoked`	401	تم إلغاء المفتاح في Settings.	أنشئ مفتاحا جديدا.
`api_key_expired`	401	لم يعد المفتاح صالحا.	أنشئ مفتاحا جديدا.
`api_scope_denied`	403	لا يملك المفتاح النطاق المطلوب.	أنشئ مفتاحا بالنطاق المطلوب.
`rate_limited`	429	طلبات كثيرة جدا في النافذة الحالية.	تراجع وأعد المحاولة لاحقا.
`validation_failed`	400	الجسم أو النموذج أو الموجه أو المعلمات غير صالحة.	قارن جسم الطلب بمرجع النموذج.
`not_found`	404	المهمة المطلوبة غير موجودة أو لا يملكها الحساب.	تحقق من معرف المهمة العام وحدود الحساب.
`webhook_url_rejected`	400	عنوان URL لنقطة webhook غير مسموح.	استخدم عنوان HTTPS عاما من دون بيانات اعتماد أو fragments أو localhost أو عناوين شبكة خاصة.
`chat_model_not_supported`	400	النموذج المحدد غير متاح لـ Chat API.	اقرأ `/api/v1/models` واختر نموذج دردشة متاحا.
`chat_session_conflict`	409	لا يمكن استخدام جلسة الدردشة لهذا الطلب.	استخدم جلسة منشأة عبر API يملكها الحساب نفسه والنموذج نفسه.
`chat_attachment_not_supported`	400	مرفق الدردشة غير مدعوم.	ارفع صورة عبر Files API ومرر `file_id` الخاص بها.
`idempotency_conflict`	409	أعيد استخدام مفتاح idempotency نفسه مع إدخال مختلف.	استخدم مفتاحا جديدا أو أعد إرسال الجسم نفسه تماما.
`insufficient_credits`	402	لا يملك الحساب رصيدا كافيا.	أضف رصيدا أو اختر طلبا أقل تكلفة.
`internal_error`	500	تعذر إكمال الطلب.	أعد المحاولة مع idempotency أو تواصل مع الدعم باستخدام `requestId`.

حدود المعدل

تطبق Rivya حدود معدل Public API على مستوى التطبيق لكل مفتاح API. يضبط حد الإنتاج الافتراضي بواسطة PUBLIC_API_RATE_LIMIT_PER_MINUTE.

عندما تتلقى rate_limited، استخدم تراجعا أسيا. لا تعد المحاولة في حلقة ضيقة.

إعادة المحاولة المتطابقة

أرسل Idempotency-Key مع كل طلب إنتاج من نوع POST /api/v1/generations وPOST /api/v1/chat/completions.

النمط الموصى به:

أنشئ مفتاحا فريدا لكل طلب توليد منطقي
أعد استخدام المفتاح نفسه فقط عند إعادة محاولة الجسم نفسه
خزّن معرف المهمة العام العائد مع سجل المهمة الخاص بك
بالنسبة إلى Chat API، خزّن session_id العائد عندما تريد متابعة المحادثة نفسها
لا تعيد استخدام مفتاح واحد لنموذج أو موجه أو معلمات مختلفة

إذا فشلت الشبكة بعد الإرسال، أعد المحاولة بالجسم نفسه وIdempotency-Key نفسه. يمكن لـ Rivya إعادة الاستجابة العامة المخزنة بدلا من إنشاء مهمة مكررة.

قرارات إعادة المحاولة

أعد محاولة هذه الأخطاء مع تراجع:

public_api_disabled
rate_limited
internal_error
أعطال الشبكة المؤقتة

لا تعد محاولة هذه الأخطاء من دون تغيير الإدخال:

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

أخطاء API وحدودها

شكل الخطأ

رموز الأخطاء المستقرة

حدود المعدل

إعادة المحاولة المتطابقة

قرارات إعادة المحاولة

صفحات ذات صلة

جدول المحتويات