# Tài liệu tham khảo lỗi

> Source: https://docs.blockvectra.com/vi/errors/

Tài liệu tham khảo này ghi lại tất cả các mã lỗi và giá trị `reason` có thể đọc được bằng máy trên các dịch vụ của BlockVectra, bao gồm việc lệnh gọi bị từ chối có bị tính phí hay không, chính sách thử lại, thời gian backoff và các hành động được khuyến nghị cho AI agent cùng các ứng dụng tự động.

Để sử dụng cho máy móc, hãy lấy danh mục hoàn chỉnh dưới dạng JSON tại [/errors.json](https://docs.blockvectra.com/errors.json). Mỗi phản hồi lỗi mang `docs_url` đều liên kết trực tiếp đến một neo (anchor) ổn định trên trang này: `https://docs.blockvectra.com/en/errors/#<reason>` (hoặc `#-<code-number>` đối với các lỗi không có mã reason).

### Lỗi JSON-RPC



| HTTP | Mã | Reason | Ý nghĩa | Tính phí | Có thể thử lại | Thời gian chờ (Retry-After) | Hành động của agent |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | `Thiếu API key: hãy gửi trong đường dẫn yêu cầu (/v1/{chain}/<api_key>) hoặc trong header x-api-key` | Không | Không | — | Đối với các endpoint JSON-RPC (/v1/{chain}), cung cấp API key trong đường dẫn yêu cầu (/v1/{chain}/<api_key>) hoặc trong header x-api-key. Đối với Top-up API (/v1/topup/*), chỉ cung cấp API key trong header x-api-key. |
| 401 | -32024 | `invalid_api_key` | `API key không xác định, bị vô hiệu hóa hoặc bị thu hồi: JSON-RPC và Data API đều trả về HTTP 401 với cấu trúc phản hồi lỗi invalid_api_key (JSON-RPC: error.code -32024 và error.data.reason invalid_api_key; Data API: error.code và error.data.reason invalid_api_key).` | Không | Không | — | Kiểm tra API key; nếu cần, hãy đăng nhập lại vào console hoặc qua đăng ký theo chương trình để tạo key mới (xem [Mất phiên hoặc API key?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | `API key đã hết hạn; hãy tạo key mới trong console` | Không | Không | — | API key đã hết hạn; hãy tạo key mới trong console hoặc qua đăng ký theo chương trình. |
| 403 | -32025 | `key_cap_exhausted` | `Hạn mức CU trọn đời của API key đã cạn kiệt; hãy tạo key mới trong console` | Không | Không | — | Hạn mức CU trọn đời của API key đã dùng hết; hãy tạo key mới trong console hoặc qua đăng ký theo chương trình. |
| 503 | -32021 | `auth_unavailable` | `Dữ liệu xác thực tạm thời không khả dụng` | Không | Có | Tuân thủ header Retry-After (giây) | Máy chủ tạm thời không thể xác minh key; đây không phải là vấn đề với key của bạn. Thử lại sau khi chờ theo Retry-After; **không tạo lại key**. |
| 404 | -32600 | `unknown_chain` | `Chuỗi không xác định` | Không | Không | — | Kiểm tra các chuỗi khả dụng qua GET /v1/chains hoặc công cụ list_chains; xác minh đường dẫn URL. |
| 404 | 404 | `unknown_endpoint` | `Phương thức và đường dẫn Data API không khớp với một thao tác đã biết` | Không | Không | — | Xác minh phương thức và đường dẫn URL theo tài liệu Data API. |
| 200 | -32700 | `parse_error` | `Lỗi phân tích cú pháp JSON` | Không | Không | — | Xác minh cú pháp JSON hợp lệ trong phần thân yêu cầu trước khi gửi. |
| 200 | -32600 | `invalid_request` | `Yêu cầu không hợp lệ` | Không | Không | — | Kiểm tra cấu trúc yêu cầu; xác minh các trường jsonrpc: '2.0', id và method trước khi gửi lại. |
| 200 | -32602 | `invalid_params` | `Tracer không được phép` | Không | Không | — | Điều chỉnh tham số phương thức; kiểm tra các tracer được hỗ trợ và giới hạn thời gian chờ cho chuỗi. |
| 200 | -32602 | `logs_range_too_large` | `Phạm vi khối eth_getLogs quá lớn: tối đa <N> khối` | Không | Không | — | Thu hẹp phạm vi khối truy vấn về trong mức max_logs_block_range được chỉ định trong GET /v1/chains. |
| 429 | -32005 | `public_rate_limit` | `Vượt quá giới hạn tần suất yêu cầu công khai` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ theo header Retry-After rồi thử lại; hoặc gửi yêu cầu kèm theo API key. [Lấy API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | `Nhóm chuỗi công khai đang bận` | Không | Có | Tuân thủ header Retry-After hoặc chờ vài giây rồi thử lại với backoff | Thử lại với backoff, hoặc gửi yêu cầu kèm theo API key. [Lấy API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | `Phương thức không khả dụng trên endpoint công khai` | Không | Không | — | Sử dụng phương thức mà endpoint công khai hỗ trợ, hoặc gửi yêu cầu kèm theo API key. [Lấy API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | `Phương thức không khả dụng trên chuỗi này hoặc đã bị vô hiệu hóa bởi chính sách` | Không | Không | — | Kiểm tra methods.allow và methods.deny trong GET /v1/chains để biết các phương thức được hỗ trợ. Hỗ trợ gửi giao dịch được xác định bởi methods.allow trong GET /v1/chains. Gửi giao dịch hiện không khả dụng trên: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | `Đăng ký WebSocket không được cung cấp trên chuỗi này` | Không | Không | — | Kiểm tra các đăng ký khả dụng cho chuỗi này qua GET /v1/chains. |
| 200 | -32602 | `logs_filter_required` | `Đăng ký logs yêu cầu một địa chỉ hoặc topic0 (giá trị không null ở vị trí topic đầu tiên)` | Không | Không | — | Chỉ định địa chỉ hoặc topic0 không null trong bộ lọc logs. |
| 200 | -32600 | `batch_too_large` | `Lô quá lớn: tối đa <N> lệnh gọi` | Không | Không | — | Chia nhỏ lô thành các lô nhỏ hơn đáp ứng giới hạn lệnh gọi tối đa được chỉ ra trong dữ liệu lỗi. |
| 413 | 413 | `request_too_large` | `Thân yêu cầu Data API vượt quá giới hạn kích thước` | Không | Không | — | Giảm kích thước thân yêu cầu. |
| 200 | -32000 | `not_found` | `Giao dịch không tìm thấy` | Không | Không | — | Nếu mới gửi hoặc mới khai thác, hãy đợi lan truyền mạng và thử lại; nếu không, hãy kiểm tra số hiệu khối hoặc mã băm. |
| 200 | -32011 | `state_window` | `Trạng thái lịch sử không khả dụng ngoài phạm vi <N> khối gần đây nhất` | Không | Không | — | Truy vấn các khối trong state_window_blocks được công bố tại GET /v1/chains, hoặc dùng Data API cho dữ liệu lịch sử. |
| 200 | -32011 | `range_not_indexed` | `Lịch sử yêu cầu chưa được lập chỉ mục hoàn toàn` | Không | Không | — | Thu hẹp lịch sử yêu cầu về phạm vi đã được lập chỉ mục; không thử lại nguyên phạm vi chưa được bao phủ. |
| 200 | -32011 | `history_not_ready` | `Lịch sử yêu cầu chưa sẵn sàng` | Không | Có | Chờ việc lập chỉ mục bắt kịp dữ liệu; tuân thủ error.data.retry_after_seconds nếu có | Thử lại khi việc lập chỉ mục bắt kịp dữ liệu, chờ số giây trong error.data.retry_after_seconds nếu được cung cấp. |
| 429 | -32005 | `key_rate_limit` | `Vượt quá giới hạn tốc độ CU của API key` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ số giây chỉ định trong header Retry-After trước khi thử lại, hoặc phân bổ tải. |
| 429 | rate_limited | `rate_limited` | `Vượt quá giới hạn tần suất yêu cầu trên API hoặc GET /v1/account (nhiều hơn 5 yêu cầu mỗi giây cho key này)` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ khoảng thời gian chỉ định trong Retry-After trước khi thử lại. |
| 429 | -32005 | `concurrency_limit` | `Vượt quá giới hạn đồng thời` | Không | Có | Tuân thủ header Retry-After hoặc chờ các lệnh gọi đang chạy hoàn tất | Giới hạn kích thước nhóm yêu cầu đồng thời của client và thử lại khi có chỗ trống. |
| 429 | -32005 | `free_plan_call_limit` | `Vượt quá giới hạn số lệnh gọi mỗi giây của gói miễn phí` | Không | Có | Chờ 1 giây trước khi thử lại | Giảm tần suất yêu cầu hoặc nạp tiền để mở mức thông lượng trả phí. |
| 429 | -32022 | `request_exceeds_burst` | `Chi phí yêu cầu <N> CU vượt quá dung lượng burst <M> CU` | Không | Không | — | Chờ đợi sẽ không giải quyết được; chia nhỏ lô hoặc giảm tham số phương thức để nằm trong dung lượng burst. |
| 429 | -32022 | `free_plan_batch_too_large` | `Yêu cầu có <N> lệnh gọi, vượt quá giới hạn gói miễn phí <M> lệnh gọi mỗi giây` | Không | Không | — | Chờ đợi sẽ không giải quyết được; chia lô để số lệnh gọi nằm trong giới hạn gói miễn phí, hoặc nạp tiền. |
| 429 | -32005 | `ws_connection_limit` | `Đã đạt giới hạn kết nối WebSocket cho key hoặc tài khoản này` | Không | Không | — | Đóng kết nối WebSocket không sử dụng hoặc dùng lại kết nối hiện có. |
| 200 | -32022 | `subscription_limit` | `Đã đạt giới hạn đăng ký WebSocket cho kết nối này` | Không | Không | — | Hủy đăng ký các sự kiện không còn cần thiết hoặc mở kết nối WebSocket mới. |
| 200 | -32005 | `ws_filter_capacity` | `Bộ lọc WebSocket logs đã đạt dung lượng tối đa` | Không | Không | — | Hủy một đăng ký logs hiện có hoặc dùng bộ lọc hẹp hơn. |
| 200 | -32026 | `ws_push_overloaded` | `Hàng đợi thông báo WebSocket bị quá tải` | Không | Có | Thử lại sau với backoff, hoặc kết nối lại | Thử lại eth_subscribe với exponential backoff, hoặc kết nối lại. Các đăng ký hiện có tiếp tục nhận thông báo. |
| 200 | -32005 | `overloaded` | `Dịch vụ quá tải, vui lòng thử lại sau` | Không | Có | Chờ vài giây rồi thử lại với exponential backoff | Áp dụng backoff với jitter rồi thử lại yêu cầu. |
| 402 | -32020 | `balance_exhausted` | `Số dư không đủ (khi biết số dư, error.data bao gồm balance_units và balance_cu)` | Không | Không | — | Nạp tiền on-chain: lấy địa chỉ nạp tiền từ console hoặc `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); xem [hướng dẫn nạp tiền cho agent](https://docs.blockvectra.com/en/guides/agent-topup/), hoặc đặt lại hạn mức trong console nếu đủ điều kiện. Khi biết số dư, error.data chứa balance_units (âm khi thấu chi) và balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | `Hạn mức miễn phí đã hết (khi biết số dư, error.data bao gồm balance_units và balance_cu)` | Không | Không | — | Nạp tiền on-chain: lấy địa chỉ nạp tiền từ console hoặc `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); xem [hướng dẫn nạp tiền cho agent](https://docs.blockvectra.com/en/guides/agent-topup/), đặt lại hạn mức nếu khả dụng hoặc chờ hạn mức của chu kỳ tiếp theo. Khi biết số dư, error.data chứa balance_units (âm khi thấu chi) và balance_cu. |
| 503 | -32021 | `billing_unavailable` | `Dữ liệu thanh toán tạm thời không khả dụng` | Không | Có | Tuân thủ header Retry-After (giây) | Đây không phải vấn đề về số dư; key mới tạo được đồng bộ trong vài giây. Chờ theo Retry-After rồi thử lại. |
| 200 | -32010 | `node_syncing` | `Node đang đồng bộ; các lệnh gọi tạm thời không khả dụng` | Không | Có | Chờ vài giây rồi thử lại | Chờ node đồng bộ xong, hoặc kiểm tra GET /v1/status. |
| 200 | -32603 | `upstream_unavailable` | `Dịch vụ upstream không khả dụng` | Không | Có | Chờ vài giây rồi thử lại | Thử lại với exponential backoff; kiểm tra GET /v1/status để biết tình trạng node. |
| 504 | 504 | `upstream_timeout` | `Dịch vụ upstream không trả lời trong giới hạn thời gian` | Không | Có | Thử lại sau một khoảng chờ ngắn | Thử lại yêu cầu với exponential backoff. |
| 200 | -32000 | `response_too_large` | `Phản hồi upstream quá lớn` | Không | Không | — | Thu hẹp tham số truy vấn (ví dụ giảm phạm vi khối trong eth_getLogs hoặc yêu cầu trace nhỏ hơn). |
| 200 | -32603 | `internal_error` | `Lỗi dịch vụ nội bộ` | Không | Không | — | Thử lại yêu cầu; báo lỗi kéo dài cho bộ phận hỗ trợ kèm thời điểm xảy ra. |
| 200 | 4444 | — | `Lịch sử đã bị tỉa bớt không khả dụng` | Không | Không | — | Khối nằm ngoài cửa sổ lịch sử được giữ lại của node đã tỉa bớt; truy vấn khối lịch sử qua Data API. |
| 200 | -32000 | — | `Trạng thái lịch sử không khả dụng; dữ liệu cũ không khả dụng do bị tỉa bớt` | Không | Không | — | Truy vấn khối trong cửa sổ trạng thái, hoặc dùng Data API để truy vấn lịch sử. |
| 200 | -32002 | — | `<node message>` | Không | Có | Chờ vài giây rồi thử lại với lô nhỏ hơn | Giảm số lệnh gọi trong lô rồi thử lại. |
| 200 | -32003 | — | `<node message>` | Không | Không | — | Chia lô thành các yêu cầu nhỏ hơn để giảm kích thước phản hồi. |
| 200 | -32601 | — | `<node message>` | Không | Không | — | Kiểm tra methods.allow và methods.deny trong GET /v1/chains để biết các phương thức được hỗ trợ. Hỗ trợ gửi giao dịch được xác định bởi methods.allow trong GET /v1/chains. Gửi giao dịch hiện không khả dụng trên: HyperEVM. |
| 200 | -32603 | — | `<node message>` | Không | Có | Thử lại sau một khoảng chờ ngắn | Thử lại yêu cầu; báo lỗi kéo dài cho bộ phận hỗ trợ kèm thời điểm xảy ra. |
| 200 | -32600 | — | `<node message>` | Không | Không | — | Kiểm tra từng yêu cầu trong lô để tìm tham số không phù hợp; chia nhỏ rồi thử lại. |
| 200 | * | — | `<node message>` | Có | Không | — | Node đã thực hiện tính toán và lệnh gọi đã bị tính phí. Kiểm tra lý do/dữ liệu revert hoặc tham số lệnh gọi; không thử lại mù quáng. |
| 408 | 408 | — | `Yêu cầu hết thời gian chờ sau 35 giây giữa thời điểm hoàn thành header yêu cầu và phản hồi` | Có thể | Có | Chờ vài giây trước khi thử lại các lệnh gọi đọc | Lệnh gọi có thể đã đến node và bị tính phí. Với lệnh gọi đọc, thử lại với backoff. Với lệnh gọi ghi (ví dụ eth_sendRawTransaction), kiểm tra trạng thái giao dịch bằng mã băm trước. |

### Mã đóng kết nối WebSocket

Mã đóng kết nối WebSocket và hành động khuyến nghị cho client.

| Mã | Reason | Ý nghĩa | Có thể thử lại | Thời gian chờ (Retry-After) | Hành động của agent |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | `Kết nối nhàn rỗi (idle)` | Có | Kết nối lại khi cần | Kết nối lại khi cần. |
| 1003 | — | `Khung nhị phân không được chấp nhận` | Không | — | Không tự động kết nối lại; chỉ gửi khung văn bản UTF-8. |
| 1009 | — | `Tin nhắn quá lớn` | Không | — | Không tự động kết nối lại; chia nhỏ yêu cầu lớn để không vượt quá 1 MiB. |
| 1012 | — | `Khởi động lại dịch vụ` | Có | Kết nối lại với backoff có jitter | Kết nối lại với backoff có jitter, đăng ký lại và truy vấn bù dữ liệu bị bỏ lỡ. |
| 1013 | — | `Chuỗi không khả dụng; quá tải` | Có | Kết nối lại với exponential backoff và full jitter | Kết nối lại với exponential backoff và full jitter, đăng ký lại và truy vấn bù dữ liệu bị bỏ lỡ. |
| 4402 | — | `Số dư không đủ` | Không | — | Không tự động kết nối lại; nạp tiền on-chain: lấy địa chỉ nạp tiền từ console hoặc `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); xem [hướng dẫn nạp tiền cho agent](https://docs.blockvectra.com/en/guides/agent-topup/), hoặc đặt lại hạn mức trong console nếu đủ điều kiện. |
| 4404 | — | `API key không hợp lệ` | Không | — | Không tự động kết nối lại; kiểm tra hoặc xoay vòng API key trong console. |
| 4408 | — | `Dịch vụ đóng phiên khi hàng đợi push vượt quá 512 KiB (524,288 byte) và hủy các thông báo đang chờ; client có thể không nhận được khung đóng (trình duyệt báo 1006); hãy xử lý các ngắt kết nối bất ngờ tương tự như 4408.` | Có | Kết nối lại với backoff; giảm đăng ký hoặc đọc nhanh hơn | Xử lý ngắt kết nối bất ngờ không có khung đóng (trình duyệt báo 1006) như 4408: kết nối lại với backoff, thiết lập lại đăng ký và truy vấn bù dữ liệu bị mất bằng eth_getLogs; giảm đăng ký hoặc đọc nhanh hơn. |
| 4429 | — | `Vượt quá tốc độ push` | Có | Kết nối lại với backoff hoặc giảm đăng ký | Giảm đăng ký hoặc kết nối lại với backoff. |
| 4503 | — | `Dịch vụ thanh toán không khả dụng` | Có | Kết nối lại với exponential backoff và full jitter | Kết nối lại với exponential backoff và full jitter, rồi đăng ký lại. |

### Lỗi Data API

Lỗi được trả về bởi các endpoint Blockchain Data API dưới /v1/data/{chain}/.

| HTTP | Mã | Reason | Ý nghĩa | Tính phí | Có thể thử lại | Thời gian chờ (Retry-After) | Hành động của agent |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | `Trùng lặp tham số truy vấn, chuỗi truy vấn không hợp lệ hoặc yêu cầu sai định dạng` | Không | Không | — | Kiểm tra tham số truy vấn; bảo đảm tham số như limit chỉ xuất hiện tối đa một lần và các tham số đều hợp lệ. |
| 409 | not_indexed_yet | — | `Số hiệu khối hoặc cửa sổ được yêu cầu vượt quá as_of_block, hoặc mã băm phân giải vượt quá as_of_block (kèm indexed_through trừ khi chuỗi chưa có khối nào được lập chỉ mục)` | Không | Có | Chờ vài giây đến khi indexed_through đạt khối yêu cầu | Thăm dò đến khi khối yêu cầu hoặc to_block không lớn hơn indexed_through, hoặc chờ chuỗi bắt đầu ghi khối. |
| 409 | window_too_large | — | `Cửa sổ khối trải dài hơn 100,000 khối và tham số clamp không được đặt thành true` | Không | Không | — | Thu hẹp phạm vi khối (from_block đến to_block) xuống <= 100,000 khối, hoặc truyền clamp=true. |
| 409 | too_many_pools | — | `Token khớp với hơn 200 pool thanh khoản; hãy truy vấn theo chiều pool thay thế` | Không | Không | — | Chỉ định pool cụ thể để truy vấn thay vì truy vấn chung theo token. |
| 409 | span_exceeded | — | `Khoảng thời gian ngày được yêu cầu vượt quá giới hạn tối đa 90 ngày` | Không | Không | — | Thu hẹp phạm vi ngày từ from_time đến to_time xuống tối đa 90 ngày. |
| 422 | no_coverage | — | `Tính năng không được hỗ trợ trên chuỗi này, hoặc khối được yêu cầu nằm trước cửa sổ dữ liệu` | Không | Không | — | Kiểm tra `features` và `coverage.from_block` trong GET /v1/data/chains (hoặc `data_features` trong GET /v1/status miễn phí) trước khi truy vấn. |
| 503 | unavailable | — | `Dịch vụ Data API tạm thời không khả dụng` | Không | Có | Chờ vài giây rồi thử lại với exponential backoff | Thử lại sau một khoảng chờ ngắn với exponential backoff. |
| 402 | insufficient_balance | — | `Số dư trả phí hoặc hạn mức miễn phí đã cạn kiệt (khi biết số dư, error.data bao gồm balance_units và balance_cu)` | Không | Không | — | Nạp tiền on-chain: lấy địa chỉ nạp tiền từ console hoặc `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); xem [hướng dẫn nạp tiền cho agent](https://docs.blockvectra.com/en/guides/agent-topup/), hoặc chờ hạn mức miễn phí được bổ sung. |
| 429 | cost_exceeds_burst | — | `Một yêu cầu duy nhất có chi phí lớn hơn dung lượng burst của key` | Không | Không | — | Chia yêu cầu thành các yêu cầu nhỏ hơn; thử lại nguyên yêu cầu sẽ không bao giờ thành công. |
| 503 | gateway_overloaded | — | `Dung lượng Data API tạm thời không khả dụng` | Không | Có | Thử lại với backoff (Retry-After: 1) | Giảm yêu cầu đồng thời trên các key và chuỗi của tài khoản này; chờ theo Retry-After trước khi thử lại. error.data.reason là null. |

### Lỗi Console, Tài khoản & Faucet API

Lỗi được trả về bởi các endpoint quản lý, cấp phát key, xác thực và faucet dưới /v1/.

| HTTP | Mã | Reason | Ý nghĩa | Tính phí | Có thể thử lại | Thời gian chờ (Retry-After) | Hành động của agent |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | `Tính năng nạp tiền tạm dừng hoặc hiện không có mạng nào khả dụng để nạp tiền; không thể cấp địa chỉ mới, nhưng các địa chỉ đã cấp trước đó vẫn được giữ nguyên cho tài khoản` | Không | Không | — | Kiểm tra khả năng nạp tiền qua GET /v1/topup/status; thử lại khi nạp tiền được bật. |
| 503 | deposit_unavailable | — | `Tạm thời không thể cấp địa chỉ nạp tiền; hãy thử lại theo header Retry-After` | Không | Có | Tuân thủ header Retry-After (giây) và dùng exponential backoff | Thử lại theo header Retry-After với exponential backoff. |
| 400 | invalid_request | `invalid_username` | `Định dạng tên người dùng không hợp lệ (phải là chữ cái, chữ số hoặc dấu gạch dưới)` | Không | Không | — | Cung cấp tên người dùng hợp lệ đáp ứng yêu cầu về ký tự và độ dài. |
| 400 | invalid_request | `expires_at` | `Thời gian hết hạn của key không ở tương lai hoặc vượt quá thời hạn hiệu lực tối đa được phép` | Không | Không | — | Đặt expires_at thành thời điểm RFC 3339 trong tương lai trong thời hạn được phép (mặc định 365 ngày), hoặc dùng expires_in_secs. |
| 400 | invalid_request | `cu_cap` | `Tham số cu_cap nằm ngoài phạm vi (phải là số nguyên từ 1 đến 9007199254740991)` | Không | Không | — | Đặt cu_cap thành số nguyên từ 1 đến 9007199254740991 hoặc bỏ qua để không giới hạn CU. |
| 400 | siwe_invalid | `expired` | `Tin nhắn Sign-In with Ethereum (SIWE) đã hết hạn hoặc nonce đã được sử dụng` | Không | Có | Lấy challenge mới ngay và ký | Yêu cầu challenge mới từ /v1/auth/siwe/challenge và ký thông điệp vừa được cấp. |
| 400 | siwe_invalid | `chain_mismatch` | `chainId trong tin nhắn SIWE không khớp với cài đặt máy chủ` | Không | Không | — | Dùng chainId trả về từ /v1/auth/siwe/challenge khi tạo thông điệp SIWE. |
| 400 | siwe_invalid | `domain_mismatch` | `domain trong tin nhắn SIWE không khớp với host của máy chủ` | Không | Không | — | Bảo đảm domain và uri khớp với host máy chủ trả về trong challenge. |
| 400 | siwe_invalid | `signature` | `Xác minh chữ ký mật mã SIWE thất bại` | Không | Không | — | Ký lại tin nhắn bằng đúng private key của ví. |
| 409 | key_limit_reached | `active_keys` | `Số lượng API key đang hoạt động (chưa bị thu hồi) đã đạt giới hạn tối đa của tài khoản` | Không | Không | — | Thu hồi các API key không còn sử dụng trước khi tạo key mới. |
| 409 | no_reset_available | `nothing_to_reset` | `Số dư đã bằng hoặc cao hơn mục tiêu đặt lại; cơ hội đặt lại được bảo lưu` | Không | Không | — | Không cần đặt lại khi số dư chưa cạn. |
| 429 | rate_limited | `daily_creations` | `Đã đạt giới hạn tạo key trong 24 giờ của tài khoản` | Không | Có | Tuân thủ header Retry-After (giây) | Xoay vòng key hiện có thay vì tạo key mới, hoặc chờ cửa sổ 24 giờ đặt lại. |
| 429 | signup_rate_limited | `per_ip` | `Đã đạt giới hạn tần suất đăng ký cho subnet IP của client` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ khoảng thời gian Retry-After trước khi tạo tài khoản mới từ mạng này. |
| 429 | signup_rate_limited | `global` | `Đã đạt giới hạn tần suất đăng ký người dùng mới toàn cầu trên tất cả các nguồn` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ khoảng thời gian Retry-After trước khi thử lại việc tạo tài khoản. |
| 400 | oauth_invalid | — | `Tham số OAuth không hợp lệ hoặc trạng thái callback không xác định, đã hết hạn hoặc đã được sử dụng` | Không | Có | — | Bắt đầu luồng đăng nhập OAuth mới từ /v1/auth/{provider}/start. |
| 400 | login_code_invalid | — | `Mã đăng nhập không xác định, đã hết hạn, đã được dùng hoặc không khớp PKCE verifier` | Không | Không | — | Bắt đầu lại đăng nhập để nhận mã đăng nhập mới. |
| 401 | unauthenticated | — | `Thiếu phiên đăng nhập, hoặc token phiên không hợp lệ, đã hết hạn hoặc bị thu hồi; trên Top-up API (/v1/topup/*), lỗi này cũng xảy ra khi header Authorization chứa token không phải Bearer hoặc không hợp lệ thay vì x-api-key` | Không | Không | — | Đăng nhập lại để lấy token phiên Bearer mới; với Top-up API, truyền API key trong header x-api-key thay vì Authorization. |
| 403 | user_disabled | — | `Tài khoản đã bị quản trị viên đình chỉ` | Không | Không | — | Liên hệ contact@blockvectra.com để được hỗ trợ tài khoản. |
| 404 | provider_disabled | — | `Nhà cung cấp OAuth được nhận diện nhưng hiện đang bị vô hiệu hóa` | Không | Không | — | Dùng SIWE hoặc nhà cung cấp xác thực khác được hỗ trợ. |
| 409 | identity_in_use | — | `Danh tính (ví hoặc tài khoản OAuth) đã được liên kết với người dùng khác` | Không | Không | — | Hủy liên kết danh tính khỏi tài khoản trước hoặc dùng danh tính khác. |
| 409 | identity_limit_reached | — | `Đã đạt số lượng danh tính liên kết tối đa (5) cho tài khoản này` | Không | Không | — | Hủy liên kết một danh tính cũ trước khi thêm danh tính mới. |
| 409 | last_identity | — | `Không thể hủy liên kết danh tính duy nhất còn lại khỏi tài khoản` | Không | Không | — | Thêm danh tính mới trước khi hủy liên kết danh tính hiện tại. |
| 409 | key_not_active | — | `Đã cố gắng xoay vòng một API key đang bị vô hiệu hóa, bị thu hồi hoặc đã hết hạn` | Không | Không | — | Tạo key mới hoặc xoay vòng key đang hoạt động. |
| 409 | no_reset_available | — | `Không còn cơ hội đặt lại hạn mức trên tài khoản này` | Không | Không | — | Nạp tiền on-chain: lấy địa chỉ nạp tiền từ console hoặc `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); xem [hướng dẫn nạp tiền cho agent](https://docs.blockvectra.com/en/guides/agent-topup/), hoặc chờ chu kỳ khuyến mại tiếp theo. |
| 413 | payload_too_large | — | `Thân yêu cầu vượt quá giới hạn kích thước 64 KiB` | Không | Không | — | Giảm kích thước payload của yêu cầu về dưới 64 KiB. |
| 503 | signup_paused | — | `Đăng ký người dùng mới toàn cầu tạm thời bị tạm dừng; các tài khoản hiện tại đăng nhập bình thường` | Không | Có | Thử lại sau | Đăng ký người dùng mới tạm dừng; kiểm tra trạng thái và thử lại sau. |
| 503 | usage_unavailable | — | `Dịch vụ báo cáo mức sử dụng tạm thời không khả dụng` | Không | Có | Chờ vài giây rồi thử lại | Chỉ ảnh hưởng endpoint /usage; các endpoint khác hoạt động bình thường. Thử lại sau một khoảng ngắn. |
| 500 | internal | — | `Lỗi máy chủ không mong muốn` | Không | Có | Thử lại sau một khoảng chờ ngắn | Thử lại yêu cầu với exponential backoff. |
| 400 | invalid_address | `invalid_address` | `Định dạng hoặc checksum của địa chỉ người nhận không hợp lệ` | Không | Không | — | Dùng 0x theo sau bởi 40 ký tự thập lục phân, viết thường hoặc có checksum EIP-55; kiểm tra data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | `Faucet không đủ tiền để chi trả yêu cầu nhận và phí giao dịch` | Không | Có | Tuân thủ header Retry-After (giây) | Chờ theo Retry-After trước khi thử lại; không cho rằng ETH test đã được gửi nếu chưa có phản hồi chấp nhận. |
| 503 | service_unavailable | `service_unavailable` | `Xử lý nhận faucet tạm thời không khả dụng, hoặc yêu cầu nhận trước đó chưa có biên lai giao dịch` | Không | Có | Tuân thủ header Retry-After | Chờ theo Retry-After trước khi thử lại; không cho rằng ETH test đã được gửi nếu chưa có phản hồi chấp nhận. |

### Lỗi Push API

Lỗi từ quản lý đăng ký webhook và lịch sử sự kiện dưới /v1/push/.

| HTTP | Mã | Reason | Ý nghĩa | Tính phí | Có thể thử lại | Thời gian chờ (Retry-After) | Hành động của agent |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | `Các trường yêu cầu, địa chỉ, phân trang hoặc phạm vi khối không hợp lệ.` | Không | Không | — | Kiểm tra data.field và data.invalid; sửa yêu cầu. |
| 401 | missing_api_key | — | `Thiếu x-api-key.` | Không | Không | — | Gửi API key trong header x-api-key. |
| 401 | invalid_api_key | — | `API key không xác định, bị vô hiệu hóa hoặc bị thu hồi.` | Không | Không | — | Dùng key đang hoạt động của tài khoản bạn. |
| 402 | insufficient_balance | — | `Số dư hoặc hạn mức miễn phí đã hết cho lịch sử sự kiện.` | Không | Không | — | Kiểm tra data.reason (balance_exhausted hoặc free_grant_exhausted) và data.balance_units / data.balance_cu nếu có; nạp tiền qua data.topup_url hoặc data.deposit_address_url. |
| 403 | key_cap_exhausted | — | `Hạn mức CU của API key đã hết cho lịch sử sự kiện.` | Không | Không | — | Kiểm tra data.cu_cap và tạo key mới trong console. |
| 403 | key_expired | — | `API key đã hết hạn.` | Không | Không | — | Dùng key chưa hết hạn của tài khoản bạn. |
| 404 | not_found | — | `Không tìm thấy route, phương thức hoặc đăng ký webhook.` | Không | Không | — | Kiểm tra đường dẫn, phương thức và tài khoản sở hữu đăng ký. |
| 409 | limit_reached | — | `Đã đạt giới hạn đăng ký hoặc cặp địa chỉ của tài khoản.` | Không | Không | — | Kiểm tra data.limit và data.max; giảm đăng ký hoặc địa chỉ. |
| 413 | request_too_large | — | `Thân yêu cầu vượt quá giới hạn của route.` | Không | Không | — | Giảm kích thước danh sách địa chỉ hoặc phân chia thành nhiều nhóm. |
| 422 | chain_not_available | — | `Chuỗi không khả dụng cho push hoặc không có trong đăng ký.` | Không | Không | — | Kiểm tra GET /v1/push/chains và chains của đăng ký. |
| 422 | chains_required | — | `Yêu cầu ít nhất một chuỗi.` | Không | Không | — | Cung cấp đối tượng chains không rỗng; dùng trạng thái offline để ngừng lắng nghe. |
| 422 | confirmations_out_of_range | — | `Độ sâu xác nhận nằm ngoài phạm vi của chuỗi.` | Không | Không | — | Chọn confirmations trong khoảng data.min đến data.max. |
| 422 | destination_not_allowed | — | `URL nhận webhook không được phép.` | Không | Không | — | Kiểm tra data.rule; dùng tên host HTTPS trên cổng 443, không có thông tin người dùng hoặc fragment. |
| 422 | block_out_of_range | — | `Phạm vi khối nằm ngoài phạm vi phát lại hoặc lịch sử khả dụng.` | Không | Không | — | Dùng data.min_block và data.max_block để điều chỉnh phạm vi. |
| 429 | cost_exceeds_burst | — | `Chi phí yêu cầu lịch sử vượt quá dung lượng burst của key.` | Không | Không | — | Kiểm tra data.reason (request_exceeds_burst) và data.max; tăng dung lượng burst trước khi thử lại. Thử lại nguyên yêu cầu không có tác dụng. |
| 429 | rate_limited | — | `Đã đạt giới hạn tần suất quản lý hoặc truy vấn lịch sử.` | Không | Có | Chờ theo Retry-After | Đối với lịch sử, hãy kiểm tra data.reason (key_rate_limit hoặc free_plan_call_limit); chờ theo số giây trong Retry-After và giảm tần suất hoặc mức đồng thời của các yêu cầu. |
| 500 | internal_error | — | `Lỗi dịch vụ không mong muốn.` | Không | Không | — | Lưu lại x-request-id và liên hệ hỗ trợ. |
| 503 | auth_unavailable | — | `Xác thực API key tạm thời không khả dụng.` | Không | Có | Chờ theo số giây trong Retry-After. | Chờ theo số giây trong Retry-After trước khi thử lại. |
| 503 | billing_unavailable | — | `Trạng thái thanh toán lịch sử tạm thời không khả dụng.` | Không | Có | Chờ theo số giây trong Retry-After. | Chờ theo số giây trong Retry-After trước khi thử lại. |
| 503 | upstream_unavailable | — | `Dịch vụ Push tạm thời không thể truy cập.` | Không | Có | Chờ theo số giây trong Retry-After. | Chờ theo số giây trong Retry-After trước khi thử lại. |
| 503 | service_unavailable | — | `Dịch vụ Push hoặc dung lượng địa chỉ tạm thời không khả dụng.` | Không | Có | Chờ theo số giây trong Retry-After. | Chờ theo số giây trong Retry-After trước khi thử lại. |

Đối với lỗi đăng ký hoặc phát lại (replay) Webhook, hãy làm theo [hướng dẫn khôi phục phân phối Push](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay). Việc tích hợp bộ nhận bắt đầu bằng [xác thực chữ ký trên body thô](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures); [ví dụ thanh toán bằng stablecoin](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks) bổ sung tính năng chống trùng lặp sự kiện, kiểm tra biên lai, bù đắp lỗ hổng dữ liệu và đối soát reorg. Xem [quy tắc thanh toán](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing) để biết cách đo lường và [kết nối lại WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) cho các gói đăng ký theo kết nối.

Đối với `logs_range_too_large`, hãy kiểm tra [các tham số phương thức eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) và làm theo [hướng dẫn về giới hạn phạm vi khối và truy vấn theo phân đoạn](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Đối với việc nhận faucet trên Robinhood Chain, hãy xem [hướng dẫn faucet testnet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) để biết điều kiện hợp lệ và cách xử lý các mã lỗi dùng chung.