# Lỗi API

> URL: https://foura.ai/vi/docs/api/errors
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Cách xử lý lỗi từ FourA API.

## Định dạng Response Lỗi

API trả về các đối tượng JSON phẳng cho tất cả các lỗi. Không có đối tượng `error` lồng nhau. Khi một lỗi có mã máy có thể đọc được, đó là một trường ở cấp cao nhất: `reason` khi đạt giới hạn gói, `code` khi thực hiện lệnh gọi proxy không có cổng thoát hợp lệ.

```json
{
  "error": "Invalid API key"
}
```

Một số lỗi bao gồm các trường bổ sung như `status`, `service`, `retryAfter`, `current`, hoặc `limits` ở cấp cao nhất:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## Theo dõi một Request

Mọi response của API (thành công hoặc lỗi) đều bao gồm một header `X-FourA-Request-Id` chứa UUID cho lệnh gọi đó, ngoại trừ phần body mà FourA hoàn toàn không thể đọc (JSON sai định dạng, hoặc body vượt quá 100 KB): trường hợp này sẽ bị từ chối trước khi ID được gán. Hãy ghi log ID này ở phía bạn. Nếu bạn cần hỏi bộ phận hỗ trợ về những gì đã xảy ra với một request cụ thể, ID đó sẽ giúp chúng tôi tìm thấy request.

```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
# Content-Type: application/json
# ...
```

## Các loại lỗi

### 400: Bad Request

Request body thiếu các trường bắt buộc, chứa giá trị không hợp lệ, hoặc chỉ định mục tiêu mà API từ chối tìm nạp.

Body không phải là JSON object hoặc array được coi là JSON sai định dạng và sẽ nhận `Invalid JSON in request body`, như hiển thị bên dưới.

Trên Single, Proxy Finder và Browser, trường bị thiếu, sai kiểu dữ liệu, hoặc nằm ngoài phạm vi cho phép sẽ được nêu tên trong thông báo dưới dạng `<field>: <reason>`. Các trường lồng nhau được nối bằng dấu chấm (`validate.status.accept`). Tối đa năm vấn đề được liệt kê, phân tách bởi `; `, và nếu vượt quá con số này thông báo sẽ kết thúc bằng `and <n> more`:

```json
{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}
```

Đây là `client_error` và không bị tính phí. Thay vào đó, Auto báo cáo trường mà nó không thể chấp nhận bên trong HTTP 200, như được mô tả trong phần Đọc lỗi từ `/api/auto/` bên dưới.

Mã 400 tương tự cũng áp dụng cho cơ chế bảo vệ SSRF. Nếu `url` của bạn phân giải thành dải IP riêng tư, loopback hoặc dải IP được bảo lưu khác (RFC 5735, RFC 6598, các khối được bảo lưu của IPv6), request sẽ bị từ chối trước khi rời khỏi mạng của FourA:

```json
{
  "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts."
}
```

`<target>` là địa chỉ, hoặc host name và địa chỉ mà nó phân giải tới. URL không phân tích cú pháp được, hoặc không phải `http://` hay `https://`, cũng sẽ nhận mã 400 tương tự.

Target trỏ đến host API của chính FourA (`eu.api.foura.ai` hoặc `api.foura.ai`) cũng nhận mã 400 trên Single, Proxy Finder, Browser và Auto, trước khi bất kỳ dữ liệu nào được fetch hoặc tính phí. Điều này thường có nghĩa là một liên kết lấy từ trang web đã bị phân giải nhầm theo URL của API thay vì URL của chính trang đó:

```json
{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
```

`<url>` chính là target chính xác như bạn đã gửi. Trang [Inspect](https://foura.ai/docs/api/inspect) là một ngoại lệ duy nhất: FourA vẫn tìm nạp `https://eu.api.foura.ai/inspect` cho bạn.

Một URL chứa dấu cách hoặc ký tự điều khiển bên trong cũng nhận mã 400, trên Single, Proxy Finder và Auto, trước khi bất kỳ thứ gì được tìm nạp hoặc tính phí. Một liên kết được sao chép nguyên văn từ một trang thường mang theo các ký tự này (`javascript: void(0)`, liên kết chia sẻ có dấu cách trong văn bản). Hãy mã hóa nó, một dấu cách thành `%20`. Trình duyệt tìm nạp URL như vậy theo cách Chrome thực hiện:

```json
{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
```

Một host name không thể tra cứu sẽ không bị từ chối. Lời gọi trả về HTTP 200 kèm `status: 0` và lý do (`could not resolve <host>: <reason>`), đồng thời không bị tính phí. Một target mà FourA kết nối tới nhưng không nhận được phản hồi HTTP (vượt giới hạn redirect, timeout kết nối hoặc đọc, bị reset) cũng trả về HTTP 200, kèm `error` và `total_time` và không có `status`: xem [Request Outcomes](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

Trên Single, response body vượt quá 128 MB sau khi giải mã sẽ dừng tại đó. Lời gọi trả về HTTP 200 kèm `"error": "Response body exceeds the 128 MB limit"` và không bị tính phí.

JSON sai định dạng trong body bị từ chối theo cách tương tự, trước khi bất kỳ trường nào được đọc:

```json
{
  "error": "Invalid JSON in request body"
}
```

Các trường `proxy` và `ignoreProxies` có các lỗi 400 riêng. Cả hai đều nhận các proxy ID mờ đục mà những response trước đó đã trả về, vì vậy bất kỳ giá trị nào khác đều không thể decode:

| Thông báo | Nguyên nhân |
|-----------|-------------|
| `Invalid proxy format` | Giá trị `proxy` không phải là proxy ID do FourA phát hành. Địa chỉ proxy thô sẽ rơi vào trường hợp này. |
| `Invalid ignoreProxies format` | Một trong các mục trong `ignoreProxies` không phải là proxy ID. |
| `Proxy not found` | ID đã được decode thành công nhưng không còn liên kết với exit node đang hoạt động. Hãy chọn một proxy mới. |
| `Managed exit: this proxy id cannot be pinned to a request` | Exit node tồn tại, nhưng đây không phải là exit node mà FourA sẽ giữ mở cho một request cụ thể. ID của premium exit sẽ rơi vào trường hợp này khi gói của bạn không còn dung lượng premium traffic. Tái sử dụng session đã trả về ID này, hoặc thực hiện lệnh gọi qua `POST /api/proxy/` và sử dụng bất kỳ exit node nào được chọn. |

**Cách khắc phục:** Kiểm tra để đảm bảo request của bạn bao gồm tất cả các trường bắt buộc, các URL sử dụng `http://` hoặc `https://` với mọi khoảng trắng được mã hóa thành `%20`, host phân giải về một địa chỉ công khai, và mọi giá trị `proxy` đều là ID được sao chép nguyên văn từ response trước đó.

Đây là các kết quả `client_error`: request chưa từng rời khỏi FourA, do đó không có tài nguyên nào bị trừ cho tài khoản của bạn.

### 401: Unauthorized

API key của bạn bị thiếu hoặc không hợp lệ.

Thiếu key:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

Khóa không hợp lệ:

```json
{
  "error": "Invalid API key"
}
```

**Cách khắc phục:** Xác minh rằng header `X-API-Key` của bạn chứa một key hợp lệ. Tạo một key mới từ [Dashboard](https://foura.ai/dashboard) nếu cần.

Mã 401 luôn có nghĩa là FourA đã kiểm tra key của bạn và từ chối nó. Khi FourA không thể kiểm tra key trong vài giây, hệ thống sẽ phản hồi bằng mã 503 `API key check temporarily unavailable` (xem bên dưới), chứ không bao giờ trả về 401.

### 403: Không có trong gói của bạn

Lượt gọi yêu cầu một endpoint hoặc một tham số mà gói của bạn không bao gồm. Phản hồi sẽ đặt `X-FourA-Limit` và đưa cùng mã đó vào body dưới trường `reason`:

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

`reason` là `plan_limit_feature` đối với endpoint mà gói dịch vụ không hỗ trợ hoặc đối với `exitCountries` cùng các trường vị trí exit trên gói không có geo targeting, và là `plan_limit_premium` đối với `exitClass: premium` trên gói không có premium exit, hoặc đối với [exit location](https://foura.ai/docs/api/endpoints#exit-location) khi đã hết lưu lượng premium. Chuỗi `error` nêu rõ tên endpoint hoặc tham số.

Mã 403 từ FourA không bao giờ liên quan đến trang web đích: trang web đích chưa từng được liên hệ. Mã 403 do trang web đích trả về sẽ đến dưới dạng HTTP 200 kèm theo `status: 403` bên trong body.

**Cách khắc phục:** Xóa tham số, gọi endpoint có trong gói dịch vụ của bạn, hoặc nâng cấp gói. Không có `Retry-After` nào được thiết lập, vì việc chờ đợi không làm thay đổi kết quả. Không có chi phí nào phát sinh: kết quả là `rate_limit`, và chỉ `success` mới bị tính phí.

### 413: Payload Quá Lớn

JSON request body lớn hơn mức FourA chấp nhận (100 KB). Phản hồi không phải là JSON và không chứa `X-FourA-Request-Id`, vì body đã bị từ chối trước khi được đọc.

**Cách khắc phục:** Gửi `data` payload nhỏ hơn. Không có chi phí nào phát sinh.

### 429: Bị Giới Hạn Tần Suất (Rate Limited)

Có hai bước kiểm tra khác nhau trả về mã 429, và chúng không chứa các trường giống nhau.

**Giới hạn riêng của gói dịch vụ.** Phản hồi thiết lập header `X-FourA-Limit` cho biết giới hạn nào đã từ chối lệnh gọi và đặt cùng mã đó trong body dưới trường `reason`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`reason` là một trong `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits`, hoặc `plan_limit_bandwidth`. Khi việc chờ đợi có tác dụng, thời gian chờ sẽ nằm trong `retry_after_seconds` và trong header `Retry-After`, không bao giờ nằm trong `retryAfter`. `plan_limit_browser_daily` không chứa cả hai, vì hạn mức được làm mới lại vào nửa đêm theo giờ UTC chứ không tính bằng giây. Không có chi phí nào bị trừ: kết quả là `rate_limit`, và chỉ `success` mới bị tính phí.

**Hạn mức dùng chung của nền tảng.** Không có header `X-FourA-Limit`, và thời gian chờ nằm trong `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` và `limits` mô tả dịch vụ trên toàn bộ lưu lượng truy cập, không phải tài khoản của bạn. Việc bị từ chối ở đây nghĩa là FourA đang bận.

**Cách khắc phục:** Chờ theo giá trị mà response trả về trong `Retry-After`, `retry_after_seconds`, hoặc `retryAfter`. Khi gặp giới hạn đồng thời hoặc rate limit, hãy giới hạn số lượng request mở thay vì gửi lại loạt request bị từ chối. Khi gặp giới hạn theo ngày hoặc theo chu kỳ thanh toán, hãy dừng lượt chạy. Xem [Rate Limits](https://foura.ai/docs/api/rate-limits) để biết chi tiết từng trường và [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel) để biết mẫu thiết kế.

### 500: Lỗi máy chủ

Đã xảy ra lỗi từ phía chúng tôi.

**Cách khắc phục:** Thử lại request sau một khoảng thời gian ngắn. Nếu lỗi vẫn tiếp diễn, hãy kiểm tra [trang trạng thái](https://updates.foura.ai/status) hoặc liên hệ hỗ trợ kèm theo `X-FourA-Request-Id` từ response bị lỗi.

### 502: Upstream không khả dụng

FourA không thể nhận phản hồi từ engine nội bộ (`Upstream unavailable`: kết nối thất bại), hoặc nhận được phản hồi không thể đọc được (`Malformed JSON from backend`).

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**Cách xử lý:** Thử lại với khoảng thời gian chờ ngắn (short backoff). Lỗi này xuất phát từ phía chúng tôi, vì vậy bạn sẽ không mất phí: kết quả là `service_error` và chỉ `success` mới bị tính phí.

### 504: Hết thời gian chờ từ máy chủ thượng nguồn (Upstream Timeout)

Engine không hoàn thành trong khoảng thời gian cho phép cho request này.

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

Lỗi 504 liên quan đến thời gian xử lý tác vụ, không phải do key, tham số hay proxy của bạn. Mục tiêu phản hồi chậm, giải quyết challenge lần đầu (cold solve) và các trang có dung lượng lớn là những nguyên nhân phổ biến.

**Cách khắc phục:** Tăng `timeout_ms` trong request (Single chấp nhận tối đa 120000, Browser tối đa 120000, Auto tối đa 180000), hoặc thử lại. FourA sẽ chờ theo khoảng thời gian bạn đã chỉ định cộng thêm một biên độ nhỏ, vì vậy việc yêu cầu thêm thời gian thực sự giúp có thêm thời gian xử lý.

### 503: Dịch vụ bị vô hiệu hóa hoặc đạt giới hạn dung lượng

Lỗi 503 nghĩa là dịch vụ tạm thời không khả dụng để bảo trì hoặc giới hạn concurrency của nền tảng đã đầy. Cả hai trường hợp đều chứa các key giống nhau: `error`, `status`, `service`, `retryAfter`, `current` và `limits`. Phân biệt chúng dựa vào chuỗi `error`, không dựa vào các trường hiện có.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` là bảo trì và `current` đọc `0` cho cả hai bộ đếm, vì request đã bị từ chối trước khi đo lường bất kỳ thông số nào. `Service at capacity` là dạng đồng thời, và ở đó `current` giữ mức sử dụng thực tế của nền tảng. Xem [Rate Limits](https://foura.ai/docs/api/rate-limits) cho cấu trúc đó.

**Cách xử lý:** Đợi `retryAfter` giây, sau đó thử lại. Trang trạng thái có liệt kê các khoảng thời gian bảo trì đang hoạt động.

Dạng 503 thứ ba không có `retryAfter`. Điều này có nghĩa là engine phía sau endpoint của bạn không thể tiếp nhận lệnh gọi: nó đang khởi động lại, gặp lỗi ở phía FourA trước khi request của bạn chạy, hoặc (trên Browser) mọi trình duyệt đều bận trong suốt 10 giây mà một trang chờ đợi. `backend_status` là trạng thái riêng của engine và `detail` là phần đầu câu trả lời của nó:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

Đây là `service_error` và không bị tính phí. Hãy thử lại sau một hoặc hai giây. Một request tự bản thân nó bị sai sẽ không bao giờ rơi vào trường hợp này: nó sẽ nhận mã 400 chỉ rõ trường bị lỗi.

Mã 503 thứ tư nghĩa là FourA tạm thời không thể xác thực API key của bạn, ví dụ như trong lúc cơ sở dữ liệu đang chuyển đổi. Vấn đề không nằm ở key của bạn và chưa có gì được thực thi. Phản hồi sẽ mang `Retry-After: 5` và cùng khoảng thời gian chờ trong `retryAfter`:

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

Lượt này không bị tính phí. Hãy thử lại sau `retryAfter` giây. Một key mà FourA đã xác nhận trong 10 phút qua vẫn tiếp tục hoạt động qua thời điểm như vậy, vì vậy kết quả này rất hiếm khi xảy ra.

## Đọc các lỗi từ `/api/auto/`

`POST /api/auto/` phản hồi bằng HTTP 200 bất cứ khi nào ladder đã chạy, ngay cả khi mọi rung đều thất bại. Kết quả thực tế nằm trong body:

```json
{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

`status` là trạng thái cuối cùng mà đích phản hồi, hoặc 502 khi không có lần thử nào tiếp cận được đích (504 khi hết thời gian trước). Mọi phản hồi thất bại từ ladder đã chạy cũng mang theo một `attemptReport` để đếm những gì các lần thử gặp phải, với một dòng `summary` an toàn để ghi log, và `meta.attemptsByEngine` cùng `meta.browserRequests` cho biết lệnh gọi đã gửi những gì. Xem [Lý do lệnh gọi Auto thất bại](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). Trường request mà Auto không thể chấp nhận (chẳng hạn như `timeout_ms` dưới 5000 hoặc trên 180000) cũng trả về theo cách tương tự: HTTP 200 với `"status": 400` và lý do trong `error`, trước khi bất kỳ lần thử nào được thực hiện và hoàn toàn không tính phí.

Vì vậy, đừng rẽ nhánh theo trạng thái transport cho Auto. Hãy đọc `status` và `error` từ body. Mã non-200 thực sự từ `/api/auto/` có nghĩa là FourA đã từ chối lệnh gọi trước khi ladder bắt đầu, hoặc không thể hoàn thành nó: 400 (JSON sai định dạng, đích riêng tư hoặc dành riêng, hoặc đích nằm trên chính API host của FourA), 401, 413, 502, 503 hoặc 504. Một giới hạn gói được phản hồi ngay từ đầu: `exitClass: premium` trên gói không có premium exit sẽ nhận mã 403 với `X-FourA-Limit: plan_limit_premium`, trước khi bất kỳ tác vụ nào được thực hiện. Mọi giới hạn khác, của bạn hoặc của nền tảng, đều được trả về bên trong mã 200 với trạng thái nằm trong body.

Khi một trang web thất bại liên tiếp nhiều lệnh gọi Auto thực hiện bằng API key của bạn, Auto sẽ phản hồi ngay lập tức các lệnh gọi tiếp theo của key đó tới trang web trong một khoảng thời gian mà không cần thử lại: `"error": "target temporarily unservable, retry later"`, `"status": 503` và `retryAfter` tính bằng giây. Thao tác này không tốn phí; hãy đợi `retryAfter` giây.

Giới hạn gói mà một trong các sub-call gặp phải cũng được trả về dưới dạng HTTP 200. Body chính là nội dung từ chối, kèm theo `reason`, cùng với `status` và `meta`, và response mang header `X-FourA-Limit` tương tự như một từ chối trực tiếp:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Những giới hạn nào dừng toàn bộ ladder và giới hạn nào chỉ đóng một nấc được giải thích trong [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Lỗi từ phía mục tiêu bên trong 200 OK

Không phải mọi lỗi đều hiển thị dưới dạng HTTP status khác 2xx. Khi mục tiêu phản hồi HTTP 200 nhưng phản hồi của FourA mang `error` (ví dụ: các quy tắc `validate` của bạn từ chối body) hoặc body là trang kiểm tra mà FourA nhận diện được, kết quả sẽ là `application_error`. Khi mục tiêu trả về status khác 200 mà các quy tắc `validate` của bạn không chấp nhận, kết quả sẽ là `application_fail` và body được giữ nguyên vẹn.

Cả hai trường hợp đều không tính phí: chỉ `success` mới bị tính phí. Một lệnh gọi Browser khi thấy mọi browser đều bận sẽ đợi tối đa 10 giây để có browser trống. Nếu không có browser nào sẵn sàng, lệnh gọi sẽ trả về mã 503 `Backend service unavailable` như đã mô tả ở trên. Browser cũng có thể phản hồi HTTP 200 kèm `"error": "No available browser slot"` khi hoàn toàn không thể lấy được browser. Cả hai đều không bị tính phí. Hãy thử lại sau vài giây, hoặc duy trì ít lệnh gọi Browser đồng thời hơn. Tài liệu tham khảo [Outcomes](https://foura.ai/docs/api/outcomes) bao gồm toàn bộ hệ thống phân loại.

Một lệnh gọi Single qua một `proxy` mà bạn đã ghim cũng có thể phản hồi HTTP 200 kèm `"error": "The exit gave the same answer for <n> different sites"` bên cạnh body. FourA phát hiện exit đó trả về cùng một trang cho các trang web không liên quan, vì vậy trang đó là của chính exit chứ không phải trang bạn yêu cầu. Trường hợp này là `application_error` và không tính phí. Hãy lấy một exit mới từ `POST /api/proxy/`, hệ thống sẽ tự động bỏ qua exit đó.

Điều tương tự cũng áp dụng khi mạng riêng của exit phản hồi thay vì trang web đích. Lệnh gọi sẽ trả về `"error": "The exit answered instead of the site (<name>)"` hoặc `"error": "Corporate web gateway intercepted the request (<name>)"` (trang đăng nhập hoặc trang lọc, hoặc lệnh chuyển hướng đến các trang này), kèm `"error": "The exit intercepted TLS and answered instead of the site (<name>)"` khi exit tự phản hồi thay cho trang web, hoặc kèm `"error": "Honeypot echo proxy (plaintext request dump)"` khi exit gửi trả lại bản sao của chính request từ bạn. FourA kiểm tra các trường hợp này bất kể quy tắc `validate` của bạn thiết lập ra sao, bao gồm cả các lượt tải xuống `returnBuffer`. Không trường hợp nào bị tính phí. Hãy lấy một exit mới theo cách tương tự.

## Mã hóa phản hồi

FourA tự động giải mã response body sang UTF-8. Nếu mục tiêu phân phối `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*` hoặc bất kỳ charset nào khác được khai báo trong header `Content-Type` hay thẻ HTML `<meta charset>`, bạn sẽ nhận được chuỗi UTF-8 chuẩn trong trường `data` (single, proxy) hoặc `body` (browser).

Đối với payload nhị phân (hình ảnh, protobuf, âm thanh raw), hãy đặt `returnBuffer: true` trên request. Khi đó, Single và Proxy sẽ trả về `data` dưới dạng một đối tượng chứa raw bytes, `{"type": "Buffer", "data": [<byte values>]}`, mà không áp dụng chuyển đổi charset.

## Chiến lược thử lại

Một chính sách thử lại thực tế:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## Lỗi Proxy Đi Kèm Báo Cáo

Một lệnh gọi `POST /api/proxy/` hết số lần thử lại sẽ trả về mã HTTP 200 kèm một error envelope, không phải là một mã lỗi HTTP. Chuỗi lỗi rất ngắn và luôn có cùng cấu trúc, vì vậy một đối tượng `attemptReport` sẽ đi kèm với số liệu thống kê:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

Ghi log `attemptReport.summary` cùng với lỗi để biết liệu các exit node bị chặn, không hoạt động, hay trả về các trang bị chính quy tắc `validate` của bạn từ chối. Tài liệu tham khảo trường thông tin và cách xử lý từng số lượng: [Lý do proxy request hết số lần thử](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## Liên quan

- [Rate Limits](https://foura.ai/docs/api/rate-limits): Giới hạn gói dịch vụ, concurrency, và chi tiết RPM
- [Chạy request song song](https://foura.ai/docs/how-to/run-requests-in-parallel): Duy trì dưới mức concurrency của gói dịch vụ
- [Kết quả request](https://foura.ai/docs/api/outcomes): Giải thích bảy giá trị outcome
- [Vấn đề thường gặp](https://foura.ai/docs/troubleshooting/common-issues): Triệu chứng, nguyên nhân, cách khắc phục
- [Kiểm tra trang web](https://foura.ai/docs/api/site-checks): Khi body là trang challenge thay vì lỗi
- [Lý do proxy request hết số lần thử](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Cách đọc `attemptReport`
