> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# مرجع رموز الأخطاء

> رموز الأخطاء والأحكام المعيارية المستخدمة عبر منصة Truthlocks. هذه الرموز مستقرة ويمكن استخدامها للتعامل مع الأخطاء برمجيًا.

رموز الأخطاء والأحكام المعيارية المستخدمة عبر منصة Truthlocks. هذه الرموز مستقرة ويمكن استخدامها للتعامل مع الأخطاء برمجيًا.

## أحكام التحقق

| الحكم | خروج CLI | الوصف |
| - | - | - |
| VALID | 0 | تم التحقق من الشهادة بنجاح |
| ALTERED | 10 | تجزئة الحمولة لا تتطابق |
| REVOKED | 11 | تم إلغاء الشهادة |
| KEY\_COMPROMISED | 12 | مفتاح التوقيع معلم على أنه مخترق |
| KEY\_EXPIRED | 13 | مفتاح التوقيع انتهت صلاحيته |
| LOG\_PROOF\_FAILED | 14 | فشل التحقق من إثبات سجل الشفافية |
| SIGNATURE\_INVALID | 15 | فشل التحقق من التوقيع التشفيري |

### أسباب التحقق

عند استدعاء [نقطة نهاية التحقق](https://docs.truthlocks.com/ar/api-reference/verify.md)، تتضمن الاستجابة مصفوفة `reasons` مع سياق إضافي. رموز السبب هذه معلوماتية وتظهر جنبًا إلى جنب مع الحكم:

| السبب | الحكم | الوصف |
| :- | :- | :- |
| `document_hash_mismatch` | `ALTERED` | `document_hash_hex` الذي قدمته لا يتطابق مع التجزئة المخزنة وقت الإنشاء |
| `document_hash_not_stored` | (أي) | تم إنشاء الإشهاد بدون تجزئة مستند، لذلك تم تخطي التحقق من تجزئة المستند |

## رموز خطأ API

### عام

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `INVALID_INPUT` | 400 | فشل التحقق من صحة الطلب |
| `INVALID_REQUEST` | 400 | نص الطلب أو المعلمات مشوهة |
| `INVALID_ID` | 400 | المعرف ليس UUID صالحًا |
| `NOT_FOUND` | 404 | لم يتم العثور على المورد |
| `UNAUTHORIZED` | 401 | المصادقة مطلوبة |
| `FORBIDDEN` | 403 | تم رفض الإذن |
| `CONFLICT` | 409 | تعارض حالة المورد |
| `INTERNAL_ERROR` | 500 | حدث خطأ غير متوقع في الخادم |
| `DB_ERROR` | 500 | فشلت عملية قاعدة بيانات |

### التصديقات والمُصدرون

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `ISSUER_NOT_TRUSTED` | 403 | يجب أن يكون المصدر في حالة `trusted` لإنشاء الشهادات |
| `KEY_INACTIVE` | 400 | مفتاح التوقيع غير نشط |

### مفاتيح API

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `NAME_REQUIRED` | 400 | مطلوب اسم مفتاح |
| `KEY_ID_REQUIRED` | 400 | معلمة معرف المفتاح مفقودة |
| `KEY_NOT_FOUND` | 404 | لم يتم العثور على مفتاح API |
| `KEY_LIMIT` | 409 | تم الوصول إلى الحد الأقصى لعدد مفاتيح API النشطة (5 لكل مستهلك) |

### المستهلك

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `CONSUMER_REQUIRED` | 400 | مطلوب مرجع بريد إلكتروني للمستهلك |

### الهوية و DID

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `MISSING_DID` | 400 | معلمة DID مطلوبة |
| `DID_NOT_FOUND` | 404 | لم يتم العثور على DID أو تم إلغاء المصدر المرتبط به |
| `MISSING_ID` | 400 | معلمة معرف المصدر مطلوبة |
| `EMAIL_NOT_VERIFIED` | 403 | لم يتم التحقق من عنوان البريد الإلكتروني |

### SSO

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `DISCOVERY_FAILED` | 400 | تعذر تحميل تكوين اكتشاف OIDC |
| `METADATA_FETCH_FAILED` | 400 | تعذر جلب بيانات تعريف SAML IdP |
| `CRYPTO_ERROR` | 500 | فشلت عملية تشفير |
| `TEST_FAILED` | 400 | لم ينجح اختبار اتصال SSO |
| `AUTH_FAILED` | 401 | فشلت مصادقة SSO |
| `INVALID_STATE` | 401 | معلمة حالة OAuth أو SAML غير صالحة |
| `EXPIRED_SESSION` | 401 | انتهت صلاحية جلسة تسجيل الدخول الموحد (SSO) |
| `REPLAY_DETECTED` | 401 | تم استخدام رمز حالة OAuth أو SAML المميز بالفعل |
| `CONFIG_ERROR` | 500 | تكوين SSO مفقود أو غير صالح |

### السياسة والحوكمة

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `POLICY_VIOLATION` | 403 | الطلب ينتهك سياسة نشطة |

### الفوترة والقيود

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `BILLING_LIMIT` | 402 | تم استنفاد حصة الفواتير للدورة الحالية |
| `LIMIT_REACHED` | 429 | تم الوصول إلى حد الحماية الشهري |
| `SEAT_LIMIT` | 402 | تم الوصول إلى حد مقاعد الفريق — قم بترقية خطتك أو إزالة عضو موجود |

### إقامة البيانات

| الرمز | HTTP | الوصف |
| :- | :- | :- |
| `REGION_MISMATCH` | 409 | المستأجر مثبت على منطقة مختلفة عن تلك التي تعالج الطلب |

## الأخطاء القابلة لإعادة المحاولة مقابل الأخطاء النهائية

عند اتخاذ قرار بإعادة محاولة طلب فاشل، استخدم رمز حالة HTTP لتحديد ما إذا كان الخطأ عابرًا أم دائمًا.

### قابل لإعادة المحاولة (مؤقت)

يتم إعادة محاولة هذه الأخطاء تلقائيًا بواسطة [SDKs](https://docs.truthlocks.com/ar/sdk/go.md) عند تكوين `MaxRetries` (أو ما يعادله):

| حالة HTTP | الرمز | متى تتم إعادة المحاولة |
| :- | :- | :- |
| `408` | انتهاء مهلة الطلب | فورًا — لم يستلم الخادم الطلب في الوقت المحدد |
| `429` | `RATE_LIMITED` | بعد المدة المحددة في رأس `Retry-After` |
| `500` | `INTERNAL_ERROR` | مع التراجع الأسي — مشكلة خادم عابرة |
| `502` | بوابة سيئة | مع تراجع أسي - الخدمة الأولية غير متاحة |
| `503` | الخدمة غير متاحة | مع التراجع الأسي — الخدمة محملة بشكل زائد مؤقتًا |
| `504` | مهلة البوابة | مع تراجع أسي - انتهت مهلة الخدمة الأولية |

### طرفي (لا تعاود المحاولة)

تشير هذه الأخطاء إلى وجود مشكلة في الطلب لن يتم حلها بإعادة المحاولة:

| حالة HTTP | أمثلة على الرموز | الإجراء |
| :- | :- | :- |
| `400` | `INVALID_INPUT`، `INVALID_REQUEST` | إصلاح حمولة الطلب |
| `401` | `UNAUTHORIZED` | تحقق من مفتاح API أو رمز المصادقة الخاص بك |
| `403` | `FORBIDDEN`، `ISSUER_NOT_TRUSTED`، `POLICY_VIOLATION` | التحقق من الأذونات أو حالة المُصدر |
| `404` | `NOT_FOUND` | تحقق من وجود معرف المورد |
| `409` | `CONFLICT` | حل تعارض الحالة قبل إعادة المحاولة |

> [!TIP]
>
> تتعامل جميع حزم تطوير البرامج الثلاثة مع الأخطاء القابلة لإعادة المحاولة تلقائيًا مع التراجع الأسي والارتعاش. تحتاج فقط إلى منطق إعادة المحاولة اليدوي إذا قمت بتعطيل عمليات إعادة المحاولة التلقائية أو كنت ترغب في سلوك مخصص بالإضافة إلى الإعدادات الافتراضية لحزمة تطوير البرامج.

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

تُرجع كل استجابة خطأ كائن JSON بحقلين:

```json theme={null}
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
```

* **`code`** — رمز خطأ مستقر وقابل للقراءة آليًا من الجداول أعلاه. استخدم هذا لمعالجة الأخطاء برمجيًا.
* **`message`** — وصف سهل القراءة لما حدث خطأ. قد تتغير الرسائل بين الإصدارات؛ لا تطابقها برمجيًا.

> [!NOTE]
>
> يتم استبدال رسائل الخطأ التي قد تكشف تفاصيل البنية التحتية (مثل سلاسل اتصال قاعدة البيانات أو أسماء المضيفين الداخلية) تلقائيًا برسالة عامة قبل إعادتها إلى العميل. يتم تسجيل التفاصيل الأصلية على جانب الخادم فقط.

## أخطاء البوابة (RFC 7807)

عندما يصل طلب إلى بوابة API ولكنه لا يتطابق مع أي مسار صالح، تُرجع البوابة استجابة خطأ منظمة تتبع مواصفات [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807). ينطبق هذا على أخطاء `404 Not Found` و `405 Method Not Allowed` على مستوى البوابة.

### تنسيق الاستجابة

تستخدم أخطاء البوابة `application/problem+json` كنوع محتوى وتتضمن أربعة حقول:

```json theme={null}
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
```

| الحقل | الوصف |
| :- | :- |
| `type` | مرجع URI يحدد نوع الخطأ. يشير إلى صفحة التوثيق هذه. |
| `title` | ملخص موجز للخطأ. إما `Not Found` أو `Method Not Allowed`. |
| `status` | رمز حالة HTTP — `404` أو `405`. |
| `detail` | شرح مقروء من قبل الإنسان للخطأ المحدد. |

### عندما ترى هذه الأخطاء

* **`404 Not Found`** — مسار الطلب لا يتطابق مع أي مسار API. تحقق جيدًا من عنوان URL، بما في ذلك بادئة إصدار `/v1/` واسم المورد.
* **`405 Method Not Allowed`** — مسار الطلب موجود، ولكن طريقة HTTP التي استخدمتها (على سبيل المثال، `DELETE` على نقطة نهاية للقراءة فقط) غير مدعومة. تحقق من [مرجع API](https://docs.truthlocks.com/ar/api-reference/attestations/mint.md) للطريقة الصحيحة.

### معالجة أخطاء البوابة في التعليمات البرمجية

إذا قمت بتحليل استجابات الأخطاء برمجيًا، فتحقق من رأس `Content-Type` لتمييز أخطاء البوابة عن أخطاء التطبيق:

* **`application/problem+json`** — خطأ على مستوى البوابة (RFC 7807). استخدم حقلي `status` و `title`.
* **`application/json`** — خطأ على مستوى التطبيق. استخدم حقلي `code` و `message`.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
```

> [!TIP]
>
> تتعامل [حزم SDK](https://docs.truthlocks.com/ar/sdk/js.md) من Truthlocks مع كلا تنسيقي الخطأ تلقائيًا. تحتاج فقط إلى التمييز بينهما إذا كنت تستدعي واجهة برمجة التطبيقات مباشرةً.

## التعدادات القانونية

> [card] الخوارزمية
>
> \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512`

> [card] حالة المُصدر
>
> * `pending` \* `trusted` \* `suspended` \* `revoked`

> [card] طبقة الثقة
>
> * `self_issued` \* `verified_org` \* `regulated_issuer`

> [card] حالة المفتاح
>
> * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED`

> [card] حالة التصديق
>
> \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED`

> [card] تقييم المخاطر
>
> * `unknown` \* `low` \* `medium` \* `high` \* `critical`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.