استخدام واجهة API
الأخطاء
تفاصيل المشكلة، ورموز أخطاء ثابتة، وما تفعله مع كل منها.
الأخطاء على صيغة problem details وفق RFC 9457 مع Content-Type: application/problem+json. اعتمد في منطقك على code لأنه ثابت، أما detail فمكتوب ليقرأه البشر وقد يتغير.
response
{
"type": "https://crawlfeed.dev/errors/insufficient_credits",
"title": "Insufficient credits",
"status": 402,
"detail": "This call costs 1 credit and the balance is 0.",
"code": "insufficient_credits",
"request_id": "req_01K5…"
}الرموز
| الرمز | الحالة | المعنى | ما الحل؟ |
|---|---|---|---|
| unauthorized | 401 | المفتاح مفقود أو بصيغة غير صحيحة أو أُلغي. | تحقق من الترويسة Authorization، وأنشئ مفتاحًا جديدًا من لوحة التحكم إن لزم. |
| insufficient_credits | 402 | رصيدك أقل من سعر الطلب. | اشترِ باقة رصيد. لم نخصم شيئًا. |
| not_found | 404 | الحساب أو المنشور أو المسار غير موجود، أو أن المنصة لا تقدّم هذه العملية. | تحقق من المعرّف أو اسم المستخدم، وراجع صفحة المنصة لمعرفة ما تقدّمه. |
| invalid_request | 400 | أحد المُعاملات مفقود أو بصيغة غير صحيحة. | اقرأ detail، ففيه اسم المُعامل. |
| rate_limited | 429 | أرسل هذا المفتاح طلبات أسرع من الحد المسموح له. | انتظر retry_after ثانية، ثم أعد المحاولة. |
| platform_unavailable | 503 | المنصة متعطلة أو تحجب الطلبات حاليًا. | أعد المحاولة مع مهلة تتزايد تدريجيًا. يُردّ الرصيد. |
| upstream_timeout | 504 | لم تردّ المنصة في الوقت المحدد. | أعد المحاولة. يُردّ الرصيد. |
| internal_error | 500 | حدث عطل من جهتنا. | أعد المحاولة، وأرسل إلينا request_id إن تكرر الخطأ. يُردّ الرصيد. |
عمليات لا تقدّمها المنصة
تختلف المنصات، وتصرّح واجهة API بذلك بدل أن تعيد قائمة فارغة توحي بـ«لا توجد بيانات». إذا طلبت من منصة عملية لا تملكها (مثل /v1/instagram/audience) تحصل على 404 not_found مع تفاصيل تذكر المسار، ولا يُخصم شيء. ويعرض جدول التغطية ما تقدّمه كل منصة.
إعادة المحاولة
أعد محاولة rate_limited وplatform_unavailable وupstream_timeout مع مهلة تتضاعف في كل مرة (exponential backoff). ولا تعِد محاولة غيرها دون تغيير. يحمل كل خطأ request_id، فأرفقه عند التواصل معنا.