Đã xem lại 2026-11-10 · Phiên bản API 2026-11-09 · Đọc Markdown
Lỗi, thử lại và khôi phục
Lỗi API dùng { "error": { "code": "…", "message": "…", "requestId": "…" } }
kèm các lỗi trường tùy chọn, lỗi điểm đến, gợi ý thử lại và cơ chế chuyển giao hành động.
Giữ requestId để hỗ trợ. Không ghi nhật ký thông tin xác thực, URL tải lên đã ký hay
nội dung yêu cầu nhạy cảm khi thu thập chẩn đoán.
| Phản hồi | Khôi phục |
|---|---|
401 unauthenticated | Kiểm tra khóa sản phẩm vắng mặt, sai định dạng hoặc đã thu hồi |
403 forbidden_scope / account_not_allowed | Xem lại các phạm vi khóa và quyền truy cập điểm đến |
402 account_limit, seat_limit, storage_limit | Xem lại quyền lợi và mức sử dụng tài nguyên của không gian làm việc |
402 subscription_inactive / trial_expired | Giải quyết trạng thái thanh toán; giữ lại bản nháp và công việc trong hàng đợi |
409 revision_conflict | Đọc phiên bản hiện tại, xem lại các thay đổi và áp dụng lại một cách có chủ đích |
409 idempotency_conflict | Khóa đã được dùng lại với nội dung khác; đối chiếu thao tác ban đầu |
409 consent_required | Nhờ một người có thẩm quyền hoàn thành cơ chế chuyển giao xem xét đã cung cấp |
409 too_late_to_cancel | Kiểm tra trạng thái gửi thực tế; không tuyên bố hủy thành công |
media_expired / media_deleting | Tải lên lại bản gốc và cập nhật bản nháp |
422 validation_failed | Sửa các trường có cấu trúc hoặc các vấn đề theo điểm đến |
429 rate_limited | Tôn trọng Retry-After; giảm đồng thời và dùng backoff |
submission_unknown | Đối chiếu kết quả bên ngoài hiện có trước khi thử gửi lần nữa |
Thử lại thao tác thay đổi an toàn
Tạo một khóa idempotency trước thao tác thay đổi đầu tiên và lưu yêu cầu chính xác của nó.
Nếu phản hồi bị mất, thao tác có thể đã thành công rồi. Phát lại
yêu cầu giống hệt với cùng khóa đó; không bao giờ tạo khóa mới chỉ vì mạng
hết thời gian chờ. Các công cụ thay đổi của MCP phát lại khóa của chúng, kể cả trong
các trường hợp thất bại transport_outcome_unknown. Bộ chuyển đổi không tự động thử lại các thao tác thay đổi.
Giới hạn tốc độ kỹ thuật của không gian làm việc không phải là tín dụng đăng bài. Dùng /usage
để biết gói hiện tại và thông tin tốc độ. Chỉ lùi lại với các lỗi tạm thời khi phù hợp;
thử lại các lỗi ủy quyền, xác thực hoặc đồng ý của con người mà không thay đổi nguyên nhân
sẽ không giúp được gì.
Thành công từng phần và quan sát
Một lô đăng/lên lịch được chấp nhận là một tập các lượt gửi độc lập. Giữ các biên nhận thành công và liên kết gốc. Khôi phục một điểm đến thất bại qua endpoint thử lại của chính nó thay vì tạo lại cả lô. Ưu tiên webhook đã ký; nếu polling, dùng số lần thử có giới hạn với độ trễ tăng dần và chuyển công việc chưa giải quyết cho một con người.