# Lỗi, timeout và chẩn đoán SDK

Dựa vào mã lỗi và request_id; không đưa password, token hoặc payload riêng tư vào log.

Nguồn: https://whypik.com/docs/sdk-errors
Nhóm: Lập trình viên
Phiên bản tài liệu: 2026-10-14.10
Ngôn ngữ: vi

## Thời gian chờ Data API

Liên kết mục: https://whypik.com/docs/sdk-errors#section-0

JavaScript Client và Node Admin SDK mặc định chờ toàn bộ request Data API tối đa 120 giây; timeoutMs cho phép 100–300000 ms. Đây là thời hạn phía SDK, không phải idle timeout giữa các lần nhận dữ liệu của Nginx. Có thể hủy bằng AbortSignal. Phiên bản SDK đã cài trước đây giữ mặc định cũ cho đến khi cập nhật.

Python Admin SDK mặc định timeout=120 giây, cho phép 0.1–300 giây; đây là timeout I/O của transport Python. Mỗi truy vấn SQL phía máy chủ tối đa 60 giây cho mọi gói. Hết thời gian chờ phía client không chứng minh thao tác ghi đã rollback: kiểm tra ID/unique key và trạng thái outcome trước khi gửi lại.

Giới hạn 5/20/50 request mỗi giây và 2/5/10 truy vấn đồng thời theo gói đã được bỏ. Data API công khai tiếp nhận đợt request dồn bằng hàng chờ bất đồng bộ; request đang chờ chưa giữ kết nối SQL hay trừ quota. Quyền truy cập và quota được kiểm tra khi bắt đầu xử lý. Mini Server vẫn có thời hạn invocation riêng 60 giây, gồm thời gian gọi các dịch vụ; tăng timeout SDK không kéo dài invocation.

```
const client = new WhyPik({
  project: PROJECT_UUID, key: PUBLIC_KEY,
  data: { timeoutMs: 120000 }
});
const rows = await client.from("products").limit(20).select();
```


## Hàng chờ Data API và kết quả ghi

Liên kết mục: https://whypik.com/docs/sdk-errors#section-1

Áp dụng cho /api/v1/data/PROJECT_UUID/... và /.whypik/data/... trên Hosting: chờ tối đa 40 giây trước xử lý, tách khỏi SQL tối đa 60 giây. Các gói dùng chung cách xếp hàng. Đợt đông có thể tăng thời gian chờ; không nên tạo một request cho từng dòng nếu có thể lấy nhiều dòng bằng một truy vấn có limit.

data_queue_full, data_queue_timeout hoặc data_gateway_draining (HTTP 503) kèm write_outcome=not_committed nghĩa là hàng chờ chưa chuyển request đó đến Database. Có thể gửi lại sau khi giảm lượng gọi; SDK không tự lặp thao tác ghi. Timeout phía client hoặc data_outcome_unknown sau khi đã chuyển xử lý không chứng minh ghi thất bại: đối chiếu ID/unique key trước khi gửi lại.

Hàng chờ có dung lượng hữu hạn; payload vẫn tối đa 256 KiB. Hủy request đang chờ sẽ bỏ nó khỏi hàng chờ khi ingress nhận biết kết nối đã đóng. Hủy sau khi bắt đầu xử lý không đồng nghĩa hủy transaction. Lỗi trước bước xác minh CORS có thể chỉ hiện như lỗi mạng trong trình duyệt; khi không đọc được phản hồi, giữ kết quả ghi ở trạng thái chưa xác định.

Cơ chế này áp dụng cho Data API công khai, không thay đổi số sandbox Mini Server hoặc API quản lý. Khả năng giữ nhiều kết nối chờ không phải cam kết hoàn tất 10.000 truy vấn SQL hay invocation Mini Server cùng lúc.


## WhyPikError

Liên kết mục: https://whypik.com/docs/sdk-errors#section-2

| Thuộc tính | Ý nghĩa |
| --- | --- |
| code / message | Mã ổn định và thông báo |
| status | HTTP status; 0 khi không có response xác nhận |
| requestId | Mã tra cứu hỗ trợ, có thể null |
| retryable | Đọc có thể thử lại có backoff; không tự retry mọi ghi |
| reauthenticationRequired | Yêu cầu đăng nhập lại |
| outcomeUnknown | Chỉ Data write chưa xác nhận kết quả (data_outcome_unknown) |


## Hướng xử lý

Liên kết mục: https://whypik.com/docs/sdk-errors#section-3

| Tình huống | Việc cần làm |
| --- | --- |
| origin_denied / invalid_project_key | Kiểm tra UUID, loại key, origin và dịch vụ đã kích hoạt |
| data_permission_denied / data_column_denied | Xem policy bảng/cột/dòng; thử mô phỏng với đúng user |
| data_query_invalid | Kiểm tra kiểu, toán tử và alias |
| Quota/rate limit | Giảm tốc, xem usage; không vòng retry liên tục |
| database_revision_conflict | Làm mới schema/types; không tự ghi đè revision mới |
| data_network_error / data_timeout | Đọc: cho thử lại. Ghi: đối chiếu outcome trước |
| data_outcome_unknown | Không tự gửi mutation mới; đối chiếu ID/unique key |
| auth_state_changed | Bỏ kết quả phiên cũ, tải lại cho user hiện tại |


## Khi báo hỗ trợ

Liên kết mục: https://whypik.com/docs/sdk-errors#section-4

Gửi thời điểm, Project UUID, mã lỗi và request_id. Mô tả hành động đã làm. Không gửi API secret, email action token, mật khẩu hoặc mã MFA. Auth credential mutations không tự retry sau lỗi mạng chưa rõ kết quả.


## Đọc tiếp

- [Auth SDK: đăng ký, phiên và khôi phục](https://whypik.com/docs/auth-reference)
- [Thêm, sửa, xóa bằng SDK](https://whypik.com/docs/data-writes)
- [Hàng đợi, lỗi và lịch sử thao tác](https://whypik.com/docs/admin-queues)