---
title: "رسائل الأخطاء المنظمة لواجهات برمجة التطبيقات HTTP - API7.ai"
description: "منذ أن بدأت العمل على مشروع Apache APISIX، كنت أحاول تحسين معرفتي وفهمي لواجهات برمجة التطبيقات HTTP. اليوم، أود أن أقدم \"تفاصيل المشكلة لواجهات برمجة التطبيقات HTTP\" RFC، المعروف أيضًا باسم https://www.rfc-editor.org/rfc/rfc7807[RFC 7807^]."
url: "https://blog.frankel.ch/structured-errors-http-apis/"
---

[Blog](https://api7.ai/ar/blog)

[Products](https://api7.ai/ar/category/products)[Technology](https://api7.ai/ar/category/technology)[Ecosystem](https://api7.ai/ar/category/ecosystem)[Case Study](https://api7.ai/ar/category/usercase)[Team & Community](https://api7.ai/ar/category/community)

Search

⌘ + K

[Blog](https://api7.ai/blog)

Technology

# رسائل الأخطاء المنظمة لواجهات برمجة التطبيقات HTTP

[![Nicolas Fränkel](https://avatars.githubusercontent.com/u/752258?v=4)](https://github.com/nfrankel)

[Nicolas Fränkel](https://github.com/nfrankel)

November 2, 2022

[Technology](https://api7.ai/category/technology)

منذ أن بدأت العمل على مشروع [Apache APISIX](https://apisix.apache.org/)، كنت أحاول تحسين معرفتي وفهمي لـ ~~REST~~ ~~RESTful~~ واجهات برمجة التطبيقات (APIs) عبر HTTP. لهذا الغرض، أقوم بقراءة ومشاهدة المصادر التالية:

- الكتب. في الوقت الحالي، أنا على وشك الانتهاء من كتاب [API Design Patterns](https://www.manning.com/books/api-design-patterns). توقع مراجعة قريبًا.
- يوتيوب. أوصي بقناة [ErikWilde](https://www.youtube.com/ErikWilde). بينما بعض الفيديوهات أفضل من غيرها، إلا أنها جميعًا تركز على واجهات برمجة التطبيقات.
- IETF RFCs. معظم RFCs ليست عن واجهات برمجة التطبيقات، ولكن شخص ودود قام بتجميع قائمة بـ [تلك التي تتعلق بها](https://standards.rest/).

اليوم، أود أن أقدم RFC "تفاصيل المشكلة لواجهات برمجة التطبيقات عبر HTTP"، المعروف أيضًا باسم [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807).

## المشكلة (المشاكل)

تفرض مبادئ REST استخدام حالة HTTP للتواصل. بالنسبة للأخطاء، يعرّف HTTP نطاقين: أخطاء العميل، `4xx`، وأخطاء الخادم، `5xx`.

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

- `400 Bad Request`: لا يمكن للخادم معالجة الطلب بسبب خطأ يُعتقد أنه من العميل.
- `402 Payment Required`: لا يمكن معالجة الطلب حتى يقوم العميل بالدفع. ومع ذلك، لا يوجد اتفاقية استخدام قياسية، وتستخدمها كيانات مختلفة في سياقات أخرى.
- `409 Conflict`: يتعارض الطلب مع الحالة الحالية للمورد المستهدف.

هنا تكمن المشكلة الأولى: تم تحديد رموز حالة HTTP للتفاعلات بين الإنسان والآلة عبر المتصفحات، وليس للتفاعلات بين الآلة والآلة عبر واجهات برمجة التطبيقات. وبالتالي، نادرًا ما يكون اختيار رمز حالة يتوافق بشكل مباشر مع حالة الاستخدام أمرًا بسيطًا. للتوضيح، [يبدو أن مارتن فاولر يفضل 409 في حالتنا](https://martinfowler.com/articles/richardsonMaturityModel.html).

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

ومع ذلك، تظهر المشاكل عندما يقرر فريق استخدام واجهة برمجة تطبيقات تابعة لجهة خارجية. في هذه الحالة، يكون اختيار هيكل الاستجابة مهمًا لأنه يعتبر الآن جزءًا من عقد: أي تغيير من قبل الموفر قد يكسر العملاء. والأسوأ من ذلك، من المحتمل أن يكون الهيكل مختلفًا من موفر لآخر.

وبالتالي، فإن هيكل تقرير الأخطاء الموحد:

- يوفر التوحيد عبر الموفرين
- يزيد من استقرار واجهة برمجة التطبيقات

## RFC 7807

[RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) يهدف إلى حل المشكلة من خلال توفير هيكل موحد للأخطاء.

الهيكل هو التالي:

![الهيكل](https://blog.frankel.ch/assets/generated/structured-errors-http-apis/problemdetails.svg)

يصف RFC الحقول:

> - `"type"` (`string`) - مرجع URI [\[RFC3986\]](https://www.rfc-editor.org/rfc/rfc3986) يحدد نوع المشكلة. تشجع هذه المواصفات على أن يوفر، عند الإشارة إليه، وثائق قابلة للقراءة البشرية لنوع المشكلة (*مثل*، باستخدام HTML [\[W3C.REC-html5-20141028\]](https://www.rfc-editor.org/rfc/rfc7807#ref-W3C.REC-html5-20141028)). عندما لا يكون هذا العضو موجودًا، يُفترض أن تكون قيمته `"about:blank"`.
> - `"title"` (`string`) - ملخص قصير وقابل للقراءة البشرية لنوع المشكلة. يجب ألا يتغير من حدوث إلى آخر للمشكلة، إلا لأغراض الترجمة (*مثل*، باستخدام التفاوض الاستباقي للمحتوى؛ انظر [\[RFC7231, Section 3.4\]](https://www.rfc-editor.org/rfc/rfc7231#section-3.4)).
> - `"status"` (`number`) - الحالة ([\[RFC7231\], Section 6](https://www.rfc-editor.org/rfc/rfc7231#section-6)) التي تم إنشاؤها بواسطة الخادم الأصلي لهذا الحدث من المشكلة.
> - `"detail"` (`string`) - شرح قابل للقراءة البشرية خاص بهذا الحدث من المشكلة.
> - `"instance"` (`string`) - مرجع URI يحدد الحدث المحدد للمشكلة. قد يوفر أو لا يوفر معلومات إضافية عند الإشارة إليه.
>
> \-- [أعضاء كائن تفاصيل المشكلة](https://www.rfc-editor.org/rfc/rfc7807#section-3.1)

يقدم RFC العينة التالية عندما لا توجد أموال كافية لإجراء تحويل مصرفي.

![مثال RFC](https://static.api7.ai/uploads/2026/01/30/JbundvX6_problemdetails-json-sample.png?imageMogr2/format/webp)

## مثال

سأستخدم أحد [العروض التوضيحية الخاصة بي](https://github.com/nfrankel/evolve-apis/) كمثال. يسلط العرض التوضيحي الضوء على عدة خطوات لتسهيل عملية تطوير واجهات برمجة التطبيقات الخاصة بك.

في الخطوة 6، أريد أن يقوم المستخدمون بالتسجيل، لذلك أقوم بتحديد عدد المكالمات في نافذة زمنية إذا لم يتم التحقق من هويتهم. لقد قمت بإنشاء مكون إضافي مخصص لـ Apache APISIX لهذا الغرض. بعد وصول عدد المكالمات إلى الحد المسموح، يعود بـ:

```
HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0

{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}
```

لنقم بتنظيم الرسالة وفقًا لـ RFC 7807.

![قواعد RFC 7807](https://static.api7.ai/2022/11/03/problemdetails-json-register.svg)

## الخاتمة

RFC 7807 لا يساعد فقط مطوري العملاء. إنه مساعدة كبيرة لمطوري واجهات برمجة التطبيقات حيث يوفر إرشادات سريعة لتجنب إعادة اختراع العجلة في كل مشروع.

**المزيد:**

- [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807)
- [Standards.REST](https://standards.rest/)
- [أخطاء العميل HTTP 4xx](https://httpwg.org/specs/rfc9110.html#status.4xx)

*نُشرت أصلاً على [A Java Geek](https://blog.frankel.ch/structured-errors-http-apis/) في 30 أكتوبر 2022*

Tags:

[Codec](https://api7.ai/tags/codec)

Share article link

Share

Related Posts

[![أسعار Kong الجديدة لعام 2025 وأفضل البدائل لـ Kong](https://static.api7.ai/uploads/2025/03/10/FKRWNsq8_2025-kong-pricing.webp)](https://api7.ai/blog/kong-konnect-pricing)

## [أسعار Kong الجديدة لعام 2025 وأفضل البدائل لـ Kong](https://api7.ai/blog/kong-konnect-pricing)

[![إدارة دورة حياة API: استراتيجيات رئيسية للنجاح](https://static.api7.ai/uploads/2025/02/19/gsEjQi5A_api-lifecycle-management.png)](https://api7.ai/blog/api-lifecycle-management-strategies)

## [إدارة دورة حياة API: استراتيجيات رئيسية للنجاح](https://api7.ai/blog/api-lifecycle-management-strategies)

Table of Contents

- [المشكلة (المشاكل)](#%D8%A7%D9%84%D9%85%D8%B4%D9%83%D9%84%D8%A9-%D8%A7%D9%84%D9%85%D8%B4%D8%A7%D9%83%D9%84)
- [RFC 7807](#rfc-7807)
- [مثال](#%D9%85%D8%AB%D8%A7%D9%84)
- [الخاتمة](#%D8%A7%D9%84%D8%AE%D8%A7%D8%AA%D9%85%D8%A9)

## Related Posts

[![قصة Coredump حول NGINX ctx و error\_page](https://static.api7.ai/2022/12/04/638c8054cf09c.png)](https://api7.ai/ar/blog/coredump-debug-story-about-nginx)

Technology

September 16, 2022

#### [قصة Coredump حول NGINX ctx و error\_page](https://api7.ai/ar/blog/coredump-debug-story-about-nginx)

في الآونة الأخيرة، ساعدنا أحد مستخدمي APISIX في تصحيح خطأ غريب يتعلق بـ coredump. نود مشاركة بعض النقاط المثيرة للاهتمام، والتي قد توفر إرشادات مفيدة لتصحيح الأخطاء في NGINX وAPISIX.

[Codec](https://api7.ai/tags/codec)

[NGINX](https://api7.ai/tags/nginx)

[Comparison to Competitors](https://api7.ai/tags/comparison-to-competitors)

[![كيفية تجنب التراجع الكارثي في التعبيرات النمطية (Regex)؟](https://static.api7.ai/2022/11/18/637727bba2b55.png)](https://api7.ai/ar/blog/how-to-avoid-catastrophic-backtracking-completely)

Technology

December 17, 2020

#### [كيفية تجنب التراجع الكارثي في التعبيرات النمطية (Regex)؟](https://api7.ai/ar/blog/how-to-avoid-catastrophic-backtracking-completely)

يشير مصطلح "Catastrophic Backtracking" في تعابير الـ Regular Expressions إلى الحالة التي يحدث فيها تراجع مكثف وغير فعال في محاولة مطابقة النمط، مما يؤدي إلى استهلاك كبير لموارد النظام ووقت تنفيذ طويل بشكل غير متوقع.

[Regex](https://api7.ai/tags/regex)

[Codec](https://api7.ai/tags/codec)

[![قرار واقعي بشأن بوابة الواجهة البرمجية (API): نظرة من داخل عملية التقييم الفني](https://static.api7.ai/uploads/2025/06/03/E7OqOddo_api-gateway-decision.webp)](https://api7.ai/ar/blog/api-gateway-decision-inside-technical-evaluation)

Technology

June 3, 2025

#### [قرار واقعي بشأن بوابة الواجهة البرمجية (API): نظرة من داخل عملية التقييم الفني](https://api7.ai/ar/blog/api-gateway-decision-inside-technical-evaluation)

استكشف عملية تقييم بوابة الواجهة البرمجية (API) في العالم الحقيقي، مع تسليط الضوء على مرونة Apache APISIX وأدائه ومزاياه كمصدر مفتوح.

[API Gateway Concept](https://api7.ai/tags/api-gateway-concept)
