# Lỗi và trạng thái trang: cái gì đã thất bại, và có nên thử lại không

> Lỗi của Search API: sáu mã HTTP (không bị tính phí), trạng thái trang trong một 200, và khi nào nên thử lại. Không cần KYC, thanh toán bằng crypto.

- URL: https://llmwebsearch.com/vi/docs/errors/
- Cập nhật lần cuối: 2026-10-22
- Đơn vị phát hành: LLMWebSearch (https://llmwebsearch.com)

Có hai loại vấn đề. Lỗi HTTP nghĩa là toàn bộ lệnh gọi thất bại, và không tốn gì. Trạng thái trang nghĩa là truy vấn đã chạy nhưng một trang không đọc được; nó nằm trong một response 200 bình thường. Agent nên xử lý cả hai, theo cách khác nhau.

**Trả lời nhanh — API LLMWebSearch có thể trả về những lỗi nào, và chúng có bị tính phí không?**

**LLMWebSearch** có sáu lỗi HTTP: `400 invalid_parameter`, `401 invalid_api_key`, `402 insufficient_credits`, `429 rate_limited`, `502 search_failed` và `504 search_timeout`. Không lỗi nào bị tính phí. Những trang không đọc được sẽ hiển thị một `content_status` bên trong một 200. Một truy vấn thành công tốn 1 credit, từ 1,20 US$/1K lượt tìm kiếm tính đến tháng 10 năm 2026. Không cần KYC; thanh toán bằng crypto.

## Có những lỗi HTTP nào?

Body luôn là `{"error": {"code": "…", "message": "…"}}`. Không lỗi nào tốn credit.

| HTTP | `code` | Nguyên nhân | Thử lại? |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | Thiếu tham số bắt buộc hoặc giá trị nằm ngoài phạm vi | Không: sửa request |
| 401 | `invalid_api_key` | Khóa bị thiếu, sai hoặc đã bị thu hồi | Không: kiểm tra khóa |
| 402 | `insufficient_credits` | Số dư không đủ trả cho lệnh gọi này | Không: mua một pack |
| 429 | `rate_limited` | Số lệnh gọi mỗi phút vượt mức tài khoản cho phép | Có, sau khi tạm dừng |
| 502 | `search_failed` | Truy vấn không thể hoàn thành | Có, với backoff |
| 504 | `search_timeout` | Không có kết quả tìm kiếm trong vòng 30 giây | Có, với backoff |

## Trạng thái trang khác gì với lỗi?

Trạng thái trang mô tả một kết quả, không phải cả lần gọi. Tìm kiếm vẫn chạy, kết quả vẫn có, và `credits_used` vẫn được đặt như thường. Chỉ nội dung của riêng trang đó bị thiếu, và `content_status` cho biết lý do: `blocked_by_robots`, `blocked_by_site_policy`, `target_refused`, `fetch_failed`, `fetch_timeout` hoặc `unsupported_content`.

Đừng coi đây là thất bại để thử lại toàn bộ tìm kiếm. Hãy dùng các kết quả khác, snippet của trang bị thiếu, hoặc một nguồn khác. Trang [định dạng phản hồi](https://llmwebsearch.com/vi/docs/response/) giải thích từng trạng thái trong một bảng.

## Tại sao không bao giờ thử lại quanh một lần từ chối?

Vì từ chối là câu trả lời của trang web, và chúng tôi tôn trọng điều đó. Trình đọc của chúng tôi tôn trọng robots.txt: nó tự giới thiệu là LLMWebSearch, tuân theo các quy tắc mà một trang viết cho nó hoặc cho tất cả robot, và bỏ qua nội dung của bất kỳ trang nào nó không được phép đọc. Một trang đặt Content-Signal: ai-input=no trong robots.txt sẽ giữ nội dung các trang của mình khỏi nội dung trong kết quả của bạn. Khi một trang từ chối reader của chúng tôi bằng 403, 429 hoặc trang challenge, chúng tôi báo đó là `target_refused` kèm trạng thái của trang trong `target_status`.

Khi một trang từ chối trình đọc của chúng tôi, kết quả trả về không có nội dung kèm trạng thái của trang: chúng tôi không bao giờ giải CAPTCHA, đăng nhập vào tài khoản hay lách qua một chặn chặn hoặc paywall. Chúng tôi cũng không thử lại bằng danh tính khác hay trình duyệt ngụy trang. Agent của bạn không nên lặp trên một trang như vậy: kết quả sẽ không thay đổi, và trang đã nói không.

## Khi nào code của tôi nên thử lại?

Chỉ với `429`, `502` và `504`. Chờ, rồi thử lại, gấp đôi thời gian chờ mỗi lần và thêm một chút ngẫu nhiên để các worker song song không thử lại cùng lúc. Ba đến năm lần là đủ; sau đó, báo lỗi.

Không bao giờ thử lại `400`, `401` hay `402`: cùng một truy vấn cho cùng một câu trả lời cho đến khi bạn thay đổi điều gì đó. Với các trang, `fetch_failed` và `fetch_timeout` có thể hoạt động sau đó, qua một tìm kiếm mới hoặc một lần gọi `/extract`. `target_refused`, `blocked_by_robots` và `blocked_by_site_policy` là cuối cùng.

*Python: thử lại 429, 502 và 504 với exponential backoff*

```python
import os
import random
import time

import requests

API = "https://llmwebsearch.com/api/v1/search"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
RETRY_ON = {429, 502, 504}


def search(body, attempts=5):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        resp = requests.post(API, headers=HEADERS, json=body, timeout=60)
        if resp.status_code == 200:
            return resp.json()
        err = resp.json().get("error", {})
        if resp.status_code not in RETRY_ON or attempt == attempts:
            raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
        time.sleep(delay + random.uniform(0, delay / 2))
        delay = min(delay * 2, 30)


data = search({"q": "how to rotate api keys without downtime"})
unread = [r["url"] for r in data["results"] if r["content_status"] not in ("ok", "not_requested")]
print("credits:", data["credits_used"], "| pages not read:", unread)

```

## Tôi nên làm gì khi gặp 402 insufficient_credits?

Dừng lại và nạp thêm. Lần gọi không chạy và không tốn gì. Để tránh dừng giữa một tác vụ dài, hãy kiểm tra số dư trước bằng `GET https://llmwebsearch.com/api/v1/credits`, miễn phí, và so với số lượng tìm kiếm bạn dự định. Nhớ rằng một tìm kiếm với `read` trên 3 cần 2 credit.

Credit đến từ các pack mua bằng số dư crypto của bạn. Credit tìm kiếm không có ngày hết hạn: phần bạn không dùng trong tháng này vẫn còn đó vào năm sau.

## Làm sao để ở dưới rate limit?

Giới hạn số lần gọi chạy cùng lúc trong code của bạn. Mỗi tài khoản có một giới hạn lượt gọi mỗi phút, hiển thị trong dashboard; hãy hỏi support và giới hạn đó có thể được nâng lên. Một pool nhỏ các worker song song, bốn đến tám cho hầu hết agent, giữ nhịp ổn định mà không bị bùng nổ. Trang [Python](https://llmwebsearch.com/vi/docs/python/) và [Node.js](https://llmwebsearch.com/vi/docs/node/) đều có ví dụ về pool như vậy.

Khi bạn gặp `429`, hãy tạm dừng trước lần thử tiếp theo thay vì gửi ngay. Thử lại ngay lập tức chỉ thêm nhiều lần gọi bị từ chối.

## Lỗi: câu hỏi thường gặp

### Một tìm kiếm với mọi trang bị từ chối có vẫn tốn một credit không?

Có, nếu bản thân tìm kiếm đã chạy: bạn vẫn nhận được các kết quả đã xếp hạng và snippet. Giá của một tìm kiếm không phụ thuộc vào việc đọc được bao nhiêu trang trong đó.

### Lỗi 401 có phải do khóa API bị thu hồi không?

Có thể. Khóa bị thu hồi, gõ sai, thiếu tiền tố `Bearer ` hoặc header không đến được chúng tôi đều cho ra `401 invalid_api_key`. Tạo một khóa API cho mỗi agent, ứng dụng hoặc đồng đội và thu hồi bất kỳ khóa nào trong dashboard mà không ảnh hưởng đến các khóa khác.

### Tại sao một trang trả về fetch_timeout?

Các trang được đọc song song, và trang nào mất hơn 15 giây sẽ được trả về không có nội dung để không giữ chậm cả câu trả lời. Các trang chậm đôi khi phản hồi ở lần thử sau.

### Tôi có xem được các lần gọi thất bại không?

Có. Lịch sử trong dashboard liệt kê các lần gọi của bạn trong 30 ngày, kể cả lần thất bại, cùng trạng thái và credit. Các lần gọi thất bại hiển thị 0 credit.

---

LLMWebSearch: LLMWebSearch là một web search API cho AI agent, trả về kết quả đã xếp hạng kèm nội dung của các trang hàng đầu ở định dạng Markdown, thanh toán bằng crypto mà không cần tải lên giấy tờ tùy thân. Credit trả trước từ 1,20 US$/1K lượt tìm kiếm không bao giờ hết hạn. Không cần KYC — không ID, không selfie, không giấy tờ. Thanh toán bằng crypto.