أخطاء Polymarket API: شرح كل رمز

يعود كل خطأ في Polymarket CLOB API بالشكل نفسه — كائن JSON بحقل واحد error — وهذا اتساق جدير بالإعجاب وعديم الفائدة تمامًا حين تحاول معرفة سبب اختفاء أمرك للتو.

{
  "error": "<message>"
}

تشرح هذه الصفحة تلك الأخطاء. تغطي أخطاء CLOB الموثقة، ورموز الحالة وأسبابها الحقيقية، و— الجزء الذي لن تجده في الوثائق الرسمية — الأخطاء التي يواجهها الناس فعلًا في بيئة الإنتاج ولم تدوّنها Polymarket قط.

لكل رسالة موثقة أيضًا صفحتها الخاصة مع الأسباب والحكم بشأن إعادة المحاولة، مدرجة في فهرس أخطاء Polymarket.

مرجع سريع لرموز الحالة

401 — أخطاء المصادقة

Unauthorized/Invalid api key

أكثر أخطاء Polymarket بحثًا. مفتاح API الخاص بك مفقود أو منتهي الصلاحية أو غير صالح. عمليًا، نادرًا ما يكون المفتاح سيئًا حقًا — بل يكون السبب واحدًا مما يلي:

1. ترسل جزءًا فقط من مجموعة بيانات الاعتماد. تحتاج مصادقة L2 في Polymarket إلى المفتاح والسر وعبارة المرور معًا. من حالات الفشل الشائعة ملء POLY_API_KEY وPOLY_PASSPHRASE مع ترك السر فارغًا — فيرسل العميل طلبًا سليم الشكل لكنه غير قابل للتوقيع.
2. انحرفت ساعة نظامك. يتضمن التوقيع طابعًا زمنيًا، والساعة المنحرفة بأكثر من بضع ثوانٍ تنتج توقيعًا يرفضه الخادم بوصفه غير صالح. هذا هو السبب الذي يكتشفه الناس أخيرًا، وهو شائع بشكل محبط على الأجهزة الافتراضية والحاويات.
3. اشتققت المفتاح لمحفظة غير التي تتداول منها. المفاتيح مرتبطة بعنوان الموقّع الذي أنشأها.
4. تستدعي نقطة نهاية مصادَقة بترويسات L1 حيث يُتوقع L2، أو العكس.

Invalid L1 Request headers

ترويسات مصادقة L1 الخاصة بك — مجموعة توقيع EIP-712 — مشوّهة، أو أن التوقيع لا يطابق العنوان الذي تدّعي أنه لك. تحقّق من أنك توقّع بالمفتاح الخاص نفسه للعنوان الموجود في الترويسة، وأن فاصل النطاق يطابق السلسلة التي تعمل عليها (Polygon، معرّف السلسلة 137). التوقيع الصالح لمعرّف سلسلة خاطئ يبقى توقيعًا صالحًا — لكن ليس لهذا الخادم.

Could not create api key / Could not derive api key!

هذان هما الخطآن وراء عبارة البحث "polymarket unable to generate api credentials". يُرجع كلاهما من نقاط نهاية المصادقة عند فشل إنشاء المفتاح أو اشتقاقه. الخطأ Could not derive api key! على GET /auth/derive-api-key يعني عادةً أنه لا يوجد مفتاح بعد لذلك الموقّع — فالاشتقاق يُرجع مفتاحًا موجودًا ولا ينشئ واحدًا. أنشئ المفتاح أولًا باستخدام POST /auth/api-key، ثم اشتقه في التشغيلات اللاحقة.

400 — أخطاء رفض الأوامر

تُرجع هذه الأخطاء حين يجتاز الأمر التحقق على مستوى النقل لكنه يفشل في قواعد العمل. وتظهر في جسم استجابة POST /order وPOST /orders.

425 — مبكر جدًا (Too Early)

رمز حالة غير مألوف يربك الناس لأنه نادر الاستخدام في بقية الويب. في Polymarket يعني أن محرك المطابقة يُعاد تشغيله. وصل طلبك خلال النافذة التي تعود فيها المنصة إلى العمل.

هذا الخطأ عابر حقًا وآمن لإعادة المحاولة حقًا — بل هو على الأرجح أنسب خطأ لإعادة المحاولة في المنصة. تراجع وحاول مجددًا؛ لا تعامله كفشل ولا تطلق تنبيهًا عند حدوثه مرة واحدة.

503 — المنصة في وضع مقيّد

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

وضع النشر فقط هو الذي يجب التعامل معه بشكل صحيح، لأنه يخبرك بالضبط متى تعود. تتضمن الاستجابة code: "post_only_mode" وretry_after_seconds، ويُرسل التأخير نفسه في ترويسة Retry-After.

{
  "error": "post-only mode: only post-only orders and cancels are allowed",
  "code": "post_only_mode",
  "retry_after_seconds": 79
}

أخطاء غير موجودة في الوثائق

هنا يذهب معظم وقت تصحيح الأخطاء الحقيقي. الأخطاء التالية لا تظهر في مرجع رموز الأخطاء لدى Polymarket لأنها لا تنشأ من تطبيق CLOB أصلًا — بل تأتي من الحافة، أو الشبكة، أو مكتبة العميل لديك. معرفة الطبقة التي أنتجت الخطأ تخبرك أين تبحث.

"The server was unable to process your request" (تعذّر على الخادم معالجة طلبك)

أكثر أخطاء Polymarket بحثًا من بين غير الموجودة في الوثائق. هذه رسالة من طبقة الحافة لا خطأ من CLOB API — وهي ما تحصل عليه حين لا يصل الطلب إلى التطبيق أبدًا، أو لا يعود منه بشكل سليم. عمليًا، الأسباب المعتادة هي:

• طلب مشوّه ترفضه الحافة قبل التوجيه — حمولة كبيرة جدًا، أو ترويسة خاطئة، أو طريقة HTTP غير صالحة للمسار.
• فشل عابر في المنبع أثناء إعادة نشر الخدمة أو تحت الضغط.
• تجاوز مستمر لحد المعدل. لأن Cloudflare تُبطئ بالإدراج في طابور بدلًا من الرفض، قد ينتهي الأمر بالعميل المتجاوز للحد بشدة إلى طلبات تنتهي مهلتها عند الحافة بدلًا من إرجاع 429 نظيف.

تعامل معه على أنه قابل لإعادة المحاولة مع التراجع، لكن إن كان مستمرًا لا عرضيًا، فتحقق من معدل طلباتك أولًا — راجع مرجع حدود المعدل — ثم من حجم حمولتك.

403 Forbidden

الرمز 403 من Polymarket ليس عادةً مشكلة مصادقة، وهذا ما يجعله مربكًا. إنه بشكل عام الحافة تحجب الطلب. المسببات الشائعة هي القيود الجغرافية على نقاط نهاية التداول، وتحدّي نطاقات IP لمراكز البيانات وشبكات VPN، والترويسات المفقودة أو غير الشبيهة بترويسات المتصفح في الطلبات التي تتوقع الحافة أن تأتي من عميل.

إذا ظهر 403 من جهازك الافتراضي السحابي فقط وليس من حاسوبك المحمول، فهي مشكلة سمعة عنوان IP، لا مشكلة شيفرة. وإذا ظهر على نقاط نهاية التداول دون نقاط نهاية بيانات الأسواق، فهو جغرافي.

أخطاء SSL وTLS والشهادات

عبارات البحث "polymarket ssl error" و"polymarket certificate error" و"polymarket https error" تتعلق دائمًا تقريبًا بجانب العميل. شهادات Polymarket سليمة؛ أما شيء ما بينك وبينها فليس كذلك. تحقّق بالترتيب من: حزمة CA قديمة (شائعة جدًا في صور Docker القديمة وبيئات Python المجمّدة)، ووكيل مؤسسي يفحص TLS ويستبدل الشهادة بشهادته، وساعة نظام منحرفة إلى حد يجعل الشهادات تبدو غير صالحة بعد أو منتهية.

# 1. Does TLS work at all, outside your app's HTTP client?
curl -sS -o /dev/null -w "%{http_code} %{ssl_verify_result}\n" \
  https://clob.polymarket.com/ok

# 2. Is your CA bundle current? (Python)
python3 -c "import certifi, os; print(certifi.where()); print(os.path.getmtime(certifi.where()))"

# 3. Is your clock right? Certificate validation depends on it.
date -u

"Service not ready" (الخدمة غير جاهزة)

رسالة من حالة بدء التشغيل: الخدمة تعمل بما يكفي للرد لكنها غير جاهزة للخدمة. عمليًا تعامل معها مثل 425 — تراجع وأعد المحاولة. يُفترض أن تزول خلال ثوانٍ، وليست شيئًا يمكنك إصلاحه من جانب العميل.

"Order manager not ready" (مدير الأوامر غير جاهز)

رسالة من حالة بدء تشغيل محرك المطابقة، وقريبة جدًا من 425 Too Early. الخدمة قابلة للوصول لكن طبقة إدارة الأوامر لم تنته من الإقلاع، لذا ستقبل اتصالك وترفض أمرك. إنها عابرة وآمنة لإعادة المحاولة مع التراجع — لكن تعامل معها كإشارة إلى التوقف عن الإرسال لبضع ثوانٍ بدلًا من الإلحاح، لأن إعادة التشغيل تعني عادةً أن الدفتر على وشك التغير تحتك.

إذا رأيتها باستمرار لا على شكل دفعات، فتحقق من حالة Polymarket قبل تصحيح شيفرتك — فلا يوجد ما يُصلح من جانب العميل.

"Couldn't get a quote" (تعذّر الحصول على تسعيرة)

يعني عادةً أنه لا توجد سيولة قائمة على الجانب الذي طلبت تسعيره، لا أن شيئًا معطّل. في أسواق Up/Down الضعيفة قرب الانتهاء يفرغ أحد الجانبين بانتظام — لا أحد يبيع Up بأي سعر حين يصبح Up مؤكدًا — لذا لا يُرجع طلب التسعير شيئًا. تُظهر بياناتنا أن هذا شائع: في عيّنة من أسواق BTC لمدة 5 دقائق، كان لدى 1,454 من 8,510 دفتر بيع فارغ على أحد الجانبين قبل 60 ثانية من الانتهاء.

تعامل معه على أنه "لا سوق" لا كخطأ: تخطَّ الصفقة، ولا تُعِد المحاولة في حلقة ضيقة. إذا أردت معرفة مدى تكرار ذلك في سلسلة تتداولها، فإن صفحات بيانات الأسواق تعرض السيولة حسب الإطار الزمني.

استثناءات مكتبات العميل

أخطاء مثل PolyApiException[status_code=None, error_message=request exception!] تأتي من عميل Python، لا من الخادم. القيمة status_code=None هي الدليل: لم تُستقبل أي استجابة HTTP قط، لذا فهذا فشل على مستوى الاتصال — DNS، أو TLS، أو انتهاء مهلة، أو مقبس منقطع — يظهر كاستثناء من المكتبة. صحّحه كمشكلة شبكة، لا كمشكلة API. ينطبق المنطق نفسه على BuilderApiKeyCreds invalid authorization 401 في عميل relayer، والذي يعني أن بيانات اعتماد builder الممرَّرة إلى العميل لم تُقبل؛ أعد اشتقاقها بدلًا من إعادة استخدام مجموعة مخزّنة مؤقتًا.

سياسة إعادة محاولة تتعامل مع كل هذا

الخلاصة العملية أن أخطاء Polymarket تقع في ثلاث فئات، والخلط بينها هو ما يجعل البوتات هشة: أعد المحاولة دون تفكير، وأعد المحاولة بعد تأخير محدد، ولا تُعِد المحاولة أبدًا.

type Decision =
  | { retry: true; delayMs: number }
  | { retry: false; reason: string };

function classify(status: number, body: { error?: string; code?: string; retry_after_seconds?: number }, attempt: number): Decision {
  const msg = (body.error ?? "").toLowerCase();
  const backoff = Math.min(2 ** attempt * 250, 8000);
  const jittered = Math.random() * backoff;

  // Never retry — the request itself is wrong.
  if (status === 401) return { retry: false, reason: "auth: check key, secret, passphrase and clock drift" };
  if (status === 404) return { retry: false, reason: "not found" };
  if (status === 400) return { retry: false, reason: `validation: ${body.error}` };

  // Mode-restricted — the server tells you when to come back.
  if (status === 503 && body.code === "post_only_mode") {
    return { retry: true, delayMs: (body.retry_after_seconds ?? 60) * 1000 };
  }
  if (status === 503) return { retry: false, reason: "exchange paused or cancel-only" };

  // Transient — safe to retry.
  if (status === 425 || status === 429 || status >= 500) return { retry: true, delayMs: jittered };
  if (msg.includes("service not ready")) return { retry: true, delayMs: jittered };

  return { retry: false, reason: `unhandled status ${status}` };
}

أخطاء لا يمكنك الخروج منها بالتصحيح

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

إذا كنت تصطدم بهذه الجدران، فأنت لا تصحح تكاملًا — بل ينقصك مصدر بيانات. تسجّل PolyTest لقطات عند لحظات زمنية محددة لأسواق Up/Down للعملات المشفرة على Polymarket أثناء تشغيلها، مع العمق الكامل لدفتر الأوامر، لذا يبقى السجل موجودًا بعد الحسم. ويغطي مرجع الأخطاء الخاص بنا أشكال أخطاء PolyTest API، وهي مملة عمدًا بالمقارنة.