Trạng thái & hỗ trợ
Chẩn đoán trước khi báo cáo
Phần tiêu đề “Chẩn đoán trước khi báo cáo”Gần như mọi lỗi được báo cáo đều thuộc một trong năm trường hợp, và mỗi trường hợp có một dấu hiệu riêng có thể phân biệt được:
| Triệu chứng | Nguyên nhân khả dĩ | Xem ở đâu |
|---|---|---|
401 unauthorized ở một lệnh gọi đã chạy được hôm qua | Khóa đã bị xoay vòng, bị vô hiệu hóa, hoặc header bị thiếu trên một nhánh code | Xác thực |
402 insufficient_balance | Số dư thấp hơn khoản tạm giữ cho lần gửi này | Tài khoản & số dư |
Một request đơn lẻ trả về 200 nhưng không có gì bị tính phí | Cả tổ hợp đều thất bại; trạng thái HTTP không phải là kết quả | Thanh toán & hoàn tiền |
| Cùng một request khi thành công khi thất bại xen kẽ nhau | Giới hạn tần suất, hoặc một Idempotency-Key bị dùng lại với các payload khác nhau | Giới hạn tần suất, Idempotency |
Một tác vụ hàng loạt nằm mãi ở processing và last_progress_at ngừng thay đổi | Một tác vụ thực sự bị kẹt, không phải một tác vụ chậm | Trạng thái tác vụ |
Trường hợp last_progress_at đáng được nói rõ: thời gian trôi qua không phải tín hiệu lỗi, một mốc thời gian đứng yên mới là. Một tác vụ 500,000 dòng có thể chạy rất lâu một cách hợp lệ. Một tác vụ mà last_progress_at không nhúc nhích là một tác vụ cần báo cáo.
Cần kèm gì trong một yêu cầu hỗ trợ
Phần tiêu đề “Cần kèm gì trong một yêu cầu hỗ trợ”Mọi trường dưới đây đều do API trả về, nghĩa là kèm chúng không tốn gì của bạn mà tiết kiệm một vòng trao đổi:
| Kèm theo | Nguồn gốc |
|---|---|
request_id | Mọi phản hồi thời gian thực, kể cả các lỗi có trả về body |
task_id | Mọi lần gửi hàng loạt và mọi phản hồi trạng thái tác vụ |
api_key_id | GET /v1/api-key — xác định khóa mà không làm lộ nó |
| Mã trạng thái HTTP và body phản hồi chính xác | Log của chính bạn; đặc biệt là trường code |
| Một mốc thời gian UTC có đến giây | Log của chính bạn |
| Request bạn đã gửi, với khóa đã được che | Code của chính bạn |
Không bao giờ dán một khóa API vào yêu cầu hỗ trợ. api_key_id xác định khóa, còn bản thân khóa thì cấp quyền truy cập số dư của bạn.
Thông tin về sự cố
Phần tiêu đề “Thông tin về sự cố”Các thông báo ở cấp tài khoản — bảo trì theo kế hoạch, dung lượng suy giảm — xuất hiện trong Bảng điều khiển, nơi cũng lưu số dư và các bản ghi. API đưa những tình trạng tương tự tới tích hợp của bạn một cách trực tiếp, dưới dạng mã lỗi thay vì văn xuôi:
| Mã | Ý nghĩa với một tích hợp đang chạy |
|---|---|
detection_capacity_unavailable | Hiện không có dung lượng. Hãy lùi lại rồi thử lại; không có gì bị tính phí. |
realtime_route_unavailable | Không có tuyến realtime khả dụng. Hãy lùi lại rồi thử lại. |
realtime_rate_limiter_unavailable | Bản thân bộ giới hạn tần suất đang hỏng, nên không thể quyết định việc nhận yêu cầu. Thử lại sau. |
realtime_fact_cache_unavailable | Một dịch vụ phụ thuộc của realtime đang hỏng. Thử lại sau. |
Đây đều là 503 và tất cả đều thuộc nhóm “đợi rồi thử lại” — xem Mã lỗi để biết toàn bộ cách phân nhóm, kể cả những lỗi nào an toàn để thử lại với cùng Idempotency-Key.
Nền tảng đang ở đâu hôm nay
Phần tiêu đề “Nền tảng đang ở đâu hôm nay”Hai sự thật vận hành có thể kiểm chứng từ bên ngoài và đáng biết trước khi bạn gửi báo cáo sự cố:
- API được phục vụ phía sau Cloudflare, nên đường truyền mạng và việc kết thúc TLS do Cloudflare vận hành thay vì trên một máy chủ gốc duy nhất.
- Mọi phản hồi đều mang
X-RateLimit-Remaining, nên một client ghi log header phản hồi có thể phân biệt “bị chặn bởi giới hạn của chính mình” với “dịch vụ đang hỏng” mà không cần hỏi ai. Nhóm chung và nhóm phát hiện cũng mangX-RateLimit-Limittrên mọi phản hồi; realtime thì không, vì nó tiêu một token bucket thay vì một mức trần cố định mỗi phút.