مركز المساعدةالمطورون وواجهة APIحل مشكلة
حل أخطاء التكاملات وAPI وWebhooks
كل رد خطأ قد يصل تكاملك، مع سببه وحله: المصادقة، والنطاقات، والمعدل، وOAuth، وWebhooks.
إذا حدثت مشكلة
ما تراه
السبب
الحل
401 Missing API key / Missing access tokenلا يوجد رمز في الطلب.
أرسل
X-Api-Key أو Authorization: Bearer.401 Invalid or expired API keyالمفتاح ملغى أو منتهٍ أو خطأ.
اعتبره فصلاً واطلب مفتاحاً جديداً. راجع أنشئ مفتاح API وألغِه.
401 Invalid or revoked access tokenرمز OAuth ملغى.
أعد تدفق OAuth.
401 Access token expiredانتهت ساعة الرمز.
جدّد بـ
refresh_token.401 Token is not bound to a workspaceرمز تالف.
أصدر رمزاً جديداً.
403 على نقطة سجلاتالنطاق ناقص (
INSUFFICIENT_SCOPE مع required_scope).أنشئ مفتاحاً بالنطاق. راجع نطاقات المفتاح وكيف تتقاطع مع الصلاحيات.
403 RESOURCE_FORBIDDENالعضو أو السجل خارج الصلاحية.
ارفع صلاحية منشئ المفتاح.
403 You cannot grant scopes you don’t holdتمنح نطاقاً لا تملكه.
اختر نطاقات أقل.
403 على إدارة الاشتراكاتالطلب بجلسة مستخدم أو بلا
read.استخدم مفتاحاً بنطاق القراءة.
429 API key rate limit exceededتجاوزت 120 طلباً في الدقيقة.
أبطئ واجمع الطلبات.
400 في الكتابةاسم حقل بدل معرّفه، أو قيمة غير صالحة.
استخدم معرّفات الحقول. راجع نقاط السجلات والتعليقات واكتشاف الحقول.
200 مع تنبيه ASSIGN_SCOPE_DENIEDتغيير المسؤول أُسقط.
أضف نطاق
assign.عدد سجلات أقل من المتوقع
مستوى المنشئ يقيّد الرؤية.
أنشئ المفتاح من عضو بمستوى أعلى.
invalid_grant: code is invalid, expired, or already usedرمز التفويض قديم.
استبدله خلال 60 ثانية.
invalid_grant: redirect_uri mismatchرابط مختلف.
طابق الرابط حرفياً.
invalid_grant: PKCE required for public clients / PKCE verification failedPKCE ناقص أو خطأ.
أرسل
code_challenge ثم code_verifier المطابق.invalid_client: bad client secretسر خطأ.
استخدم السر الصحيح.
invalid_grant: refresh tokenرمز تجديد مستخدم أو منتهٍ.
أعد الاتصال. لا تستخدم رمز تجديد قديماً أبداً.
Webhook لا يصل
رابط غير HTTPS، أو رد غير
2xx، أو تغيير من مفتاحك نفسه.توقيع لا يطابق
جسم أُعيد تسلسله.
تحقق على الجسم الخام. راجع تحقق من توقيع Webhook وامنع التكرار.
حدث مكرر
إعادة محاولة.
امنع التكرار بمعرّف التسليم.
هل حلّ هذا الدليل مشكلتك؟
إن لم يحلها، سنسألك عمّا كان ناقصاً.