{"title":"الأخطاء ومعالجتها","slug":"errors","category":"api","summary":"رموز حالة HTTP وتنسيق استجابة الخطأ وكيفية التعافي من الأخطاء الشائعة.","audience":["human","llm"],"tags":["api","errors","troubleshooting","http"],"difficulty":"beginner","updated":"2026-06-27","word_count":476,"read_minutes":2,"llm_context":"Error format: { statusCode, error, message, docs? }\nCommon errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)\n401 → check Mind Key/JWT, see /docs/getting-started/authentication\n404 → wrong path, GET /endpoints for valid list, do NOT guess paths\n429 → rate limited (?key= is 60/min), use Bearer header instead\n500 → server error, retry with backoff, check /health\ndocs field in error response links to relevant documentation.\n","lang":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# الأخطاء ومعالجتها\n\nيستخدم Synapse رموز حالة HTTP القياسية مع تنسيق استجابة خطأ متسق.\nتشرح هذه الصفحة كيفية تفسير الأخطاء والتعافي منها.\n\n## تنسيق استجابة الخطأ\n\nتُرجع جميع الأخطاء JSON بهذا الهيكل:\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n| الحقل | الوصف |\n|-------|-------------|\n| `statusCode` | رمز حالة HTTP |\n| `error` | اسم حالة HTTP |\n| `message` | وصف خطأ قابل للقراءة البشرية |\n| `docs` | URL للوثائق ذات الصلة (عند الاقتضاء) |\n\n## رموز حالة HTTP\n\n### 200 OK\n\nنجاح. تمت معالجة الطلب بشكل صحيح.\n\n### 201 Created\n\nنجاح. تم إنشاء مورد جديد (مثل `POST /memory`).\n\n### 204 No Content\n\nنجاح. لم يُرجع نصًا (مثل `DELETE /memory/:id`).\n\n### 400 Bad Request\n\nكان الطلب غير صالح. الأسباب الشائعة:\n\n- حقول JSON مطلوبة مفقودة\n- صياغة JSON غير صالحة\n- قيمة enum غير صالحة (مثل فئة خاطئة)\n\n```json\n{\n \"statusCode\": 400,\n \"error\": \"Bad Request\",\n \"message\": \"category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials\"\n}\n```\n\n**الإصلاح:** تحقق من نص الطلب مقابل وثائق API. تأكد من وجود جميع الحقول\nالمطلوبة بقيم صالحة.\n\n### 401 Unauthorized\n\nفشلت المصادقة. الأسباب الشائعة:\n\n- ترويسة `Authorization` مفقودة\n- Mind Key أو JWT غير صالح\n- استخدام Mind Key حيث يُطلب JWT (أو العكس)\n\n```json\n{\n \"statusCode\": 401,\n \"error\": \"Unauthorized\",\n \"message\": \"Mind Key fehlt oder ungültig.\",\n \"docs\": \"https://synapse.schaefer.zone/docs/getting-started/authentication\"\n}\n```\n\n**الإصلاح:** تحقق من رمزك. راجع [المصادقة](/docs/getting-started/authentication).\n\n### 403 Forbidden\n\nأنت مُصادق لكن غير مسموح لك بأداء هذا الإجراء. الأسباب الشائعة:\n\n- محاولة حذف عقل مستخدم آخر\n- محاولة التحقق من ذاكرة باستخدام Mind Key (يتطلب JWT)\n- العقل معطّل\n\n**الإصلاح:** تحقق مما كنت تستخدم نوع الرمز الصحيح لنقطة النهاية هذه.\n\n### 404 Not Found\n\nالمسار أو المورد المطلوب غير موجود.\n\n> [!CRITICAL]\n> **لا تخمّن مسارات نقاط النهاية.** فقط المسارات المذكورة في `GET /endpoints`\n> موجودة. إذا حصلت على 404، فقد استخدمت مسارًا خاطئًا.\n\n```json\n{\n \"statusCode\": 404,\n \"error\": \"Not Found\",\n \"message\": \"Route GET /memory/list not found\",\n \"docs\": \"https://synapse.schaefer.zone/docs/api/errors\"\n}\n```\n\n**الإصلاح:** استدعِ `GET /endpoints` لرؤية قائمة نقاط النهاية الصالحة. قارن\nعنوان URL الخاص بك بالقائمة حرفًا بحرف.\n\n### 409 Conflict\n\nيتعارض الطلب مع الحالة الحالية. الأسباب الشائعة:\n\n- محاولة التسجيل ببريد إلكتروني موجود مسبقًا\n- URL مكرر لـ webhook\n\n**الإصلاح:** استخدم قيمة مختلفة، أو استخدم `PUT` لتحديث المورد الموجود.\n\n### 429 Too Many Requests\n\nبلغت حد المعدل. ينطبق فقط على مصادقة معامل الاستعلام `?key=` (60/دقيقة).\n\n```json\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\nترويسات الاستجابة:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\n```\n\n**الإصلاح:** بدّل إلى ترويسة `Authorization: Bearer` (بلا حد معدل)، أو انتظر\nعدد ثواني `Retry-After`.\n\n### 500 Internal Server Error\n\nخطأ في الخادم. لا ينبغي حدوث ذلك — وإذا حدث، فهو خطأ برمجي.\n\n**الإصلاح:**\n\n1. أعد المحاولة مع تراجع أُسي (1 ث، 2 ث، 4 ث، 8 ث)\n2. تحقق من `GET /health` لمعرفة ما إذا كان الخادم يعمل\n3. إذا استمر، أبلغ عن الخطأ\n\n### 503 Service Unavailable\n\nالخادم متوقف مؤقتًا (مثل أثناء النشر أو ترحيل قاعدة البيانات).\n\n**الإصلاح:** انتظر وأعد المحاولة. تحقق من `GET /health`.\n\n## أنماط التعافي\n\n### إعادة المحاولة مع تراجع أُسي\n\n```python\nimport time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n for attempt in range(max_retries):\n try:\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {KEY}\"})\n if r.status_code == 429:\n wait = int(r.headers.get(\"Retry-After\", 60))\n time.sleep(wait)\n continue\n if r.status_code >= 500:\n time.sleep(2 ** attempt)\n continue\n return r\n except requests.RequestException:\n time.sleep(2 ** attempt)\n raise Exception(f\"Failed after {max_retries} retries\")\n```\n\n### معالجة خطأ المصادقة\n\n```python\ndef safe_call(url, key):\n r = requests.get(url, headers={\"Authorization\": f\"Bearer {key}\"})\n if r.status_code == 401:\n # Mind Key غير صالح — نبه المستخدم\n raise AuthError(\"Mind Key invalid or expired\")\n return r\n```\n\n## سيناريوهات الأخطاء الشائعة\n\n### \"Mind Key fehlt oder ungültig\"\n\n- نسيت ترويسة `Authorization`\n- استخدمت `?key=` لكن الرمز خاطئ\n- تستخدم JWT حيث يُطلب Mind Key\n\n### \"Route not found\"\n\n- خمّنت مسارًا غير موجود\n- استخدمت فعلًا خاطئًا (مثل `GET /memory` مقابل `POST /memory`)\n- تحقق من `GET /endpoints` للمسارات الصالحة\n\n### \"Rate limit exceeded\"\n\n- تستخدم `?key=` وتجاوزت 60 طلبًا/دقيقة\n- بدّل إلى ترويسة `Authorization: Bearer`\n\n## الخطوات التالية\n\n- [المصادقة](/docs/getting-started/authentication)\n- [نظرة عامة على الـ API](/docs/api/overview)\n- [حدود المعدل](/docs/api/rate-limits)\n","content_html":"

الأخطاء ومعالجتها

\n

يستخدم Synapse رموز حالة HTTP القياسية مع تنسيق استجابة خطأ متسق.\nتشرح هذه الصفحة كيفية تفسير الأخطاء والتعافي منها.

\n

تنسيق استجابة الخطأ

\n

تُرجع جميع الأخطاء JSON بهذا الهيكل:

\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
الحقلالوصف
statusCodeرمز حالة HTTP
errorاسم حالة HTTP
messageوصف خطأ قابل للقراءة البشرية
docsURL للوثائق ذات الصلة (عند الاقتضاء)
\n

رموز حالة HTTP

\n

200 OK

\n

نجاح. تمت معالجة الطلب بشكل صحيح.

\n

201 Created

\n

نجاح. تم إنشاء مورد جديد (مثل POST /memory).

\n

204 No Content

\n

نجاح. لم يُرجع نصًا (مثل DELETE /memory/:id).

\n

400 Bad Request

\n

كان الطلب غير صالح. الأسباب الشائعة:

\n\n
{\n  "statusCode": 400,\n  "error": "Bad Request",\n  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"\n}

الإصلاح: تحقق من نص الطلب مقابل وثائق API. تأكد من وجود جميع الحقول\nالمطلوبة بقيم صالحة.

\n

401 Unauthorized

\n

فشلت المصادقة. الأسباب الشائعة:

\n\n
{\n  "statusCode": 401,\n  "error": "Unauthorized",\n  "message": "Mind Key fehlt oder ungültig.",\n  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"\n}

الإصلاح: تحقق من رمزك. راجع المصادقة.

\n

403 Forbidden

\n

أنت مُصادق لكن غير مسموح لك بأداء هذا الإجراء. الأسباب الشائعة:

\n\n

الإصلاح: تحقق مما كنت تستخدم نوع الرمز الصحيح لنقطة النهاية هذه.

\n

404 Not Found

\n

المسار أو المورد المطلوب غير موجود.

\n
**لا تخمّن مسارات نقاط النهاية.** فقط المسارات المذكورة في `GET /endpoints`\nموجودة. إذا حصلت على 404، فقد استخدمت مسارًا خاطئًا.
{\n  "statusCode": 404,\n  "error": "Not Found",\n  "message": "Route GET /memory/list not found",\n  "docs": "https://synapse.schaefer.zone/docs/api/errors"\n}

الإصلاح: استدعِ GET /endpoints لرؤية قائمة نقاط النهاية الصالحة. قارن\nعنوان URL الخاص بك بالقائمة حرفًا بحرف.

\n

409 Conflict

\n

يتعارض الطلب مع الحالة الحالية. الأسباب الشائعة:

\n\n

الإصلاح: استخدم قيمة مختلفة، أو استخدم PUT لتحديث المورد الموجود.

\n

429 Too Many Requests

\n

بلغت حد المعدل. ينطبق فقط على مصادقة معامل الاستعلام ?key= (60/دقيقة).

\n
{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

ترويسات الاستجابة:

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42

الإصلاح: بدّل إلى ترويسة Authorization: Bearer (بلا حد معدل)، أو انتظر\nعدد ثواني Retry-After.

\n

500 Internal Server Error

\n

خطأ في الخادم. لا ينبغي حدوث ذلك — وإذا حدث، فهو خطأ برمجي.

\n

الإصلاح:

\n
    \n
  1. أعد المحاولة مع تراجع أُسي (1 ث، 2 ث، 4 ث، 8 ث)
    2. \n
  2. تحقق من GET /health لمعرفة ما إذا كان الخادم يعمل
    3. \n
  3. إذا استمر، أبلغ عن الخطأ
    4. \n
\n

503 Service Unavailable

\n

الخادم متوقف مؤقتًا (مثل أثناء النشر أو ترحيل قاعدة البيانات).

\n

الإصلاح: انتظر وأعد المحاولة. تحقق من GET /health.

\n

أنماط التعافي

\n

إعادة المحاولة مع تراجع أُسي

\n
import time\nimport requests\n\ndef call_with_retry(url, max_retries=3):\n    for attempt in range(max_retries):\n        try:\n            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})\n            if r.status_code == 429:\n                wait = int(r.headers.get("Retry-After", 60))\n                time.sleep(wait)\n                continue\n            if r.status_code >= 500:\n                time.sleep(2 ** attempt)\n                continue\n            return r\n        except requests.RequestException:\n            time.sleep(2 ** attempt)\n    raise Exception(f"Failed after {max_retries} retries")

معالجة خطأ المصادقة

\n
def safe_call(url, key):\n    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})\n    if r.status_code == 401:\n        # Mind Key غير صالح — نبه المستخدم\n        raise AuthError("Mind Key invalid or expired")\n    return r

سيناريوهات الأخطاء الشائعة

\n

"Mind Key fehlt oder ungültig"

\n\n

"Route not found"

\n\n

"Rate limit exceeded"

\n\n

الخطوات التالية

\n\n","urls":{"html":"/docs/api/errors","text":"/docs/api/errors?format=text","json":"/docs/api/errors?format=json","llm":"/docs/api/errors?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}