# Response Headers

> URL: https://foura.ai/ar/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

يتضمن كل response من FourA API مجموعة صغيرة من الـ headers المخصصة. وهي مفيدة للتتبع والدعم وتسوية الفواتير والتحليل اللاحق.

## Headers يضبطها FourA

| Header | يُضبط عند | الوصف |
|--------|--------|-------------|
| `X-FourA-Request-Id` | كل response لـ `/api/*`، بما في ذلك الأخطاء وحالات 401، باستثناء body لا يستطيع FourA قراءته إطلاقاً (`400 Invalid JSON in request body`، `413`)، والذي يتم رفضه قبل تعيين معرف | UUID يحدد هذا الـ request. سجله في سجلاتك. |
| `X-FourA-Credits` | كل response لـ `/api/*` وصل إلى الـ backend | الرصيد المستهلك في هذا الاستدعاء. يُعاد عند النجاح وعند الفشل (تم تنفيذ العمل في الحالتين). |
| `X-FourA-Limit` | كل `403` أو `429` ينتج عن أحد حدود خطتك | الحد الذي رفض الاستدعاء: `plan_limit_` متبوعاً بـ `feature`، أو `premium`، أو `concurrency`، أو `rate`، أو `browser_daily`، أو `credits`، أو `bandwidth`. |
| `Retry-After` | حالات `429` لحدود الخطة التي يزيلها الانتظار (التزامن، ومعدل الطلبات، والرصيد، وعرض النطاق الترددي) و 503 `API key check temporarily unavailable` | ثواني الانتظار، كعدد صحيح. يطابق `retry_after_seconds` في body حد الخطة و `retryAfter` في رمز 503. |
| `X-FourA-Exit-Class` | كل استدعاء `/api/proxy/` أو `/api/auto/` حدد `exitClass` وقام بتسليم صفحة، وكل استدعاء Single أو Browser تم تقديمه عبر مخرج مميز | `premium` أو `standard`: فئة المخرج الذي قام بتسليم الـ body. استدعاء Proxy الفاشل لم يسلم شيئاً ولا يحمل أي قيمة. |
| `X-FourA-Browser-Used-Today` | كل استجابة `POST /api/browser/` لم ترفضها حدود خطتك، وكل استجابة `POST /api/auto/` أرسل تسلسلها request لم ترفضه الحدود | طلبات Browser المحتسبة اليوم على حسابك: انظر أدناه. |
| `X-FourA-Browser-Limit-Per-Day` | نفس الاستجابات، عندما تحدد خطتك عدداً يومياً | طلبات Browser التي تسمح بها خطتك يومياً. |
| `X-FourA-Check-Page` | استجابات Single و Proxy Finder و Browser التي يكون فيها HTTP 200 body صفحة فحص bot أو صفحة رفض يتعرف عليها FourA | اسم الصفحة، على سبيل المثال `amazon-captcha`. لا يتم احتساب تكلفة هذا الـ request: انظر [Request Outcomes](https://foura.ai/docs/api/outcomes). |
| `Content-Type` | كل response | دائماً `application/json` للغلاف (envelope). يُعاد content-type للهدف داخل حقل `headers` الخاص بالغلاف. |

## X-FourA-Request-Id

يتم تمييز كل استدعاء إلى `POST /api/auto/`، أو `POST /api/single/`، أو `POST /api/proxy/`، أو `POST /api/browser/` بـ UUID. يتم ضبط الـ header حتى عند فشل المصادقة، لتتمكن من ربط الاستدعاءات الخاطئة أيضاً.

```bash
curl -i -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'
```

```
HTTP/1.1 200 OK
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...
```

### حالات الاستخدام

- **تذاكر الدعم الفني**: قم بتضمين معرف الـ request وسنتمكن من العثور على الاستدعاء بدقة في سجلاتنا.
- **سجلاتك الخاصة**: احفظه بجانب سطر سجل تطبيقك. إذا وردت شكوى من عميل تفيد بأن "البيانات كانت غير صحيحة عند الساعة 14:32"، يمكنك إعادة تنفيذ نفس الـ request بدقة.
- **التتبع عبر لوحة التحكم**: يظهر المعرف نفسه في [موجز النشاط](https://foura.ai/docs/dashboard/activity-log) للمفاتيح التي تديرها، مما يتيح لك فتح الصف المطابق وفحص الـ request والـ response الملتقطين.

### مثال: التسجيل من جانبك

```python
import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
```

```javascript
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}
```

## X-FourA-Credits

يُبلغ `X-FourA-Credits` عن تكلفة الرصيد للاستدعاء الذي قمت به للتو. إنه مقياس استهلاك وليس فاتورة: يعكس header ما استهلكه العمل بغض النظر عن النتيجة. تحتسب طبقة الفوترة في لوحة التحكم النتائج الخاضعة للفوترة فقط ضمن خطتك (راجع [نتائج الطلب](https://foura.ai/docs/api/outcomes) لمعرفة النتائج الخاضعة للفوترة).

### مرجع التكلفة

| Engine | Base | With `unblocker` |
|--------|------|------------------|
| Single | 1 | 2 |
| Proxy | 2 | 4 |
| Browser | 5 | 10 (when a defense was solved) |

يُمثل `/api/auto/` طلبًا واحدًا على لوحة التحكم الخاصة بك، وتكون تكلفة رصيده هي مجموع الاستدعاءات الفرعية التي أجراها داخليًا (قد تنتهي إعادة تشغيل واحدة على هدف جاهز بتكلفة 2، بينما يمكن أن يستهلك الحل الأولي على موقع صعب تكلفة أكبر بكثير). تتطابق قيمة `X-FourA-Credits` في استجابة auto مع `meta.credits` في جسم الاستجابة، وتتتبع تكلفة المسار بالكامل.

### لماذا يتوفر في كل من header وحقل body؟

يتميز الـ header بسهولة الاستخدام: يمكنك قراءته قبل تحليل الـ body، أو تسجيله بجانب سطر الطلب الخاص بك، أو حسابه عبر استدعاءات متعددة دون الحاجة إلى معالجة JSON. في وضع Auto، يتضمن `meta.credits` في الـ body نفس الرقم. لا تحتوي أجسام Single وProxy وBrowser عليه، لذا فإن الـ header هو المكان الوحيد لقراءته في تلك الاستجابات. يظهر أيضًا في صف [النشاط](https://foura.ai/docs/dashboard/activity-log) الخاص بكل استدعاء.

## X-FourA-Limit

لا يظهر `X-FourA-Limit` إلا عندما يرفض أحد حدود خطتك الاستدعاء. لا تقوم حدود معدل الاستخدام المشتركة للنظام بتعيينه مطلقًا، لذا فإن الـ header هو أسرع طريقة للتمييز بين "خطتي أوقفت هذا" و"FourA مشغول" دون تحليل الـ body.

```
HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json
```

تأتي قيمتان من القيم السبع برمز 403 بدلا من 429: `plan_limit_feature` (الـ endpoint أو المعامل `exitCountries` غير مشمولين في خطتك) و `plan_limit_premium` (`exitClass: premium` غير مشمول في خطتك). لا يقوم أي منهما بتعيين `Retry-After`، لأن الانتظار لن يغير النتيجة.

```python
STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))
```

القيم السبع وحقول body المرافقة لكل منها موجودة في [Rate Limits](https://foura.ai/docs/api/rate-limits).

## X-FourA-Exit-Class

يحدد `X-FourA-Exit-Class` فئة المخرج الذي قام بتسليم الـ body: القيمة `premium` عندما يقدمه مخرج premium، والقيمة `standard` عندما تقدمه المجموعة standard. يظهر هذا الـ header في استجابة `POST /api/proxy/` أو `POST /api/auto/` التي سلمت صفحة كلما حدد الـ request قيمة `exitClass`، حيث يحمل الـ body نفس القيمة (`exitClass` في Proxy، و`meta.exitClass` في Auto)، ويظهر في استجابة Single أو Browser كلما كان الـ `proxy` الذي قمت بتثبيته مخرج premium، حيث لا يحتوي الـ body على حقل له. استدعاء Proxy أو Auto الفاشل لم يقدم أي محتوى، وبالتالي لا يحمل الـ header ولا الحقل.

```
HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

يُحسب traffic عبر premium exit ضمن premium traffic الخاص بك وكذلك ضمن إجمالي bandwidth. يتم قياسه على الشبكة ويشمل محاولات premium التي لم تُرجع صفحتك، لذا فإن أي request تمت الإجابة عليه بواسطة `standard` قد يكون استهلك جزءًا من premium traffic، في محاولة فشلت قبل أن يجيب الـ standard pool. يُحدد هذا header الفئة التي قامت بالتسليم، وليس ما إذا كان قد تم استخدام premium traffic أم لا: تُظهر علامة **premium** في صف [Activity](https://foura.ai/docs/dashboard/activity-log) وصفحة [Usage & Limits](https://foura.ai/docs/dashboard/quota) ما تم احتسابه. ما يقوم به `exitClass` ومتى يتم استخدام premium exit: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today و X-FourA-Browser-Limit-Per-Day

يحمل هذان الـ headers حصة المتصفح اليومية الخاصة بك في الـ response نفسه، وهي نفس الأرقام التي تعرضها صفحة [Usage & Limits](https://foura.ai/docs/dashboard/quota)، حتى تتمكن من متابعتها دون الحاجة للتحقق المستمر من dashboard.

```
HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

يبدأ العد مجددا عند منتصف الليل بتوقيت UTC ويشمل كل مفتاح في خطتك، وليس فقط المفتاح الذي أجرى هذا الاستدعاء. الطلب الذي رفضته حدود خطتك لا يحمل أيا من header: يحتوي جسمه على `used_today` و `limit_per_day` بدلا من ذلك، راجع [Rate Limits](https://foura.ai/docs/api/rate-limits).

في `POST /api/browser/` يتضمن العد الطلب الذي تقرأه. وفي `POST /api/auto/` يمثل أعلى عد تلقاه ladder أثناء تشغيله، لذا قد يتأخر عن إجمالي اليوم بسبب طلباتك الأخرى التي لا تزال قيد التشغيل. الاستجابة التلقائية Auto التي لم ترسل أي طلب، مثل فترة التوقف لمدة 120 ثانية بعد حالات الفشل المتكررة في أحد المواقع، لا تحمل أيا من header. ما استهلكه استدعاء Auto واحد من العد موجود في `meta.browserRequests`: راجع [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## سلوك التخزين المؤقت

لا تعين API القيمة `Cache-Control`. يمكن أن تحمل الاستجابة قيمة `ETag` ضعيفة محسوبة من جسمها، ولكن لا يتم تخزين أي شيء مؤقتا: كل استدعاء يصل إلى backend. إذا كنت بحاجة إلى التخزين المؤقت، فأضفه من جانبك.

## ترويسات استجابة الهدف

إن headers التي أعادها الموقع الهدف ليست موجودة في استجابة FourA API. بل تعود داخل غلاف JSON في حقل `headers`. بالنسبة لنقاط النهاية Single و Proxy، يكون هذا مصفوفة من كائنات headers لكل قفزة (إدخال واحد لكل خطوة إعادة توجيه). أما بالنسبة لنقطة النهاية Browser، فهو كائن مسطح يحتوي على headers للاستجابة النهائية.

```json
{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}
```

إذا كنت بحاجة إلى header هدف محدد، فاقرأه من حقل `headers` الخاص بـ envelope، وليس من استجابة HTTP لطلب API نفسه.

## ذو صلة

- [API Endpoints](https://foura.ai/docs/api/endpoints): هياكل مغلفات request وresponse
- [API Errors](https://foura.ai/docs/api/errors): كيفية تنظيم استجابات الأخطاء
- [Request Outcomes](https://foura.ai/docs/api/outcomes): أي النتائج قابلة للفوترة
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): سجل لكل request مفهرس حسب معرّف request
- [Rate Limits](https://foura.ai/docs/api/rate-limits): ما يعنيه كل قيمة لـ `X-FourA-Limit`
