Gửi mã xác thực

Đọc trạng thái HTTP, error.code và error.numeric_code theo thao tác đang gọi. Mã số có kiểu chuỗi. Giữ request_id để chẩn đoán; đây không phải khóa chống lặp hay mã tác vụ.

Hợp đồng công khai định nghĩa 30016 khi mã xác thực bị từ chối, nhưng luồng hiện có vẫn có thể trả provider_invalid_request / 30001. Xử lý cả hai, không giả định lần từ chối nào cũng có 30016.

invalid_request · 10000 · 400

Kiểm tra JSON và các trường bắt buộc.

Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

Đích ghi đè workspace trống hoặc sai định dạng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.

Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.

Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

Kiểm tra các trường và định dạng riêng của kênh.

Xử lý và thử lại: Sửa tham số theo thao tác và điều kiện của kênh rồi mới gọi lại. Lặp lại yêu cầu sai y nguyên không khắc phục lỗi.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

unsupported_action · 30005 · 400

Thao tác tài khoản không được nhận diện; dùng thao tác trong tài liệu.

Xử lý và thử lại: Chọn kênh và thao tác được tài liệu ghi là hỗ trợ. Lặp yêu cầu không bổ sung tính năng hay cấp quyền beta.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 400 · 30005

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}

invalid_api_key · 11001 · 401

Kiểm tra API Key có đúng và được bật hay không.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Thêm tiêu đề X-Api-Key.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

Ví dụ · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

Yêu cầu cố ghi đè workspace mà API Key không được phép dùng. Bỏ tiêu đề ghi đè và dùng API Key thuộc workspace đích.

Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

Không tìm thấy workspace được ghi đè hoặc workspace không khả dụng. Kiểm tra chủ sở hữu, bỏ tiêu đề ghi đè và dùng API Key của workspace đích; gọi lặp không cấp thêm quyền.

Điều kiện: Áp dụng khi yêu cầu có tiêu đề X-Workspace-Id để ghi đè workspace.

Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_already_authorized · 20016 · 409

Tài khoản đã xác thực xong nên thao tác từ chối xác thực trùng. Làm mới trạng thái và dùng lại kết quả đã hoàn tất; không lặp xác thực hoặc hủy theo vòng.

Điều kiện: Áp dụng khi xác thực TikTok hoàn tất đồng thời với việc gửi mã xác thực hoặc hủy xác thực.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

Kênh áp dụng: TikTok

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20016

{
  "request_id": "req_example",
  "error": {
    "code": "account_already_authorized",
    "numeric_code": "20016",
    "message": "Account is already authorized; re-authentication is not required"
  }
}

account_binding_not_found · 30006 · 409

Tài khoản chưa gắn với kết nối kênh hoạt động; kiểm tra trạng thái.

Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

duplicate_provider_account · 20015 · 409

Danh tính kênh này đã gắn với tài khoản khác trong không gian làm việc.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20015

{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}

egress_configuration_pending · 20032 · 409

Hiện chưa thể xác nhận hoặc tải cấu hình mạng mặc định của nền tảng. Điều này không có nghĩa là tài khoản đã đăng xuất.

Điều kiện: Thao tác này dùng dung lượng mạng do nền tảng phân bổ hoặc cấu hình mạng mặc định cố định của tài khoản.

Xử lý và thử lại: Lưu request_id và kiểm tra tài khoản hoặc kết quả tạo trước khi ghi lại. Chờ dung lượng hoặc cấu hình phục hồi, hoặc liên hệ hỗ trợ. Không tự động tạo tài khoản, đổi mạng hay khởi động lại liên tục.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20032

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

provider_account_mismatch · 20017 · 409

Danh tính kênh trong yêu cầu không khớp với liên kết tài khoản.

Xử lý và thử lại: Giữ request_id và mã lỗi có cấu trúc; kiểm tra thao tác hiện tại trước khi chọn hành động tiếp theo.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20017

{
  "request_id": "req_example",
  "error": {
    "code": "provider_account_mismatch",
    "numeric_code": "20017",
    "message": "Authenticated provider account does not match the bound account; re-scan with the original account"
  }
}

provider_not_ready · 30009 · 409

Kết nối chưa sẵn sàng. Kiểm tra ủy quyền và runtime_status trước khi thử lại.

Xử lý và thử lại: Kiểm tra trạng thái xác thực và runtime rồi chọn làm mới, khởi động hoặc kết nối lại theo mục tiêu và khả năng kênh. Lỗi kết nối không tự chứng minh đã đăng xuất. Xác nhận running trước thao tác nghiệp vụ cần kết nối.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

wallet_account_creation_in_progress · 20030 · 409

Một tài khoản thanh toán bằng ví đang được tạo trong không gian làm việc này, hoặc tài khoản đích chưa khởi tạo xong.

Xử lý và thử lại: Khi yêu cầu tạo tài khoản bị xung đột, hãy chờ theo Retry-After và dùng lại Idempotency-Key nếu đã gửi khóa đó trong yêu cầu ban đầu. Nếu yêu cầu xác thực trả về lỗi này, dùng billing.operation_id trong phản hồi tạo tài khoản để gọi GET /v1/account-operations/{operation_id}. Chờ data.state=SUCCEEDED rồi thử lại thao tác ban đầu trên chính tài khoản đó. billing.state=ACTIVE không có nghĩa là đã khởi tạo xong; không tạo tài khoản khác.

Kênh áp dụng: Telegram

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 409 · 20030

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_account_creation_in_progress",
    "numeric_code": "20030",
    "message": "Account creation is in progress; please wait"
  }
}

run_auth_action_failed · 20010 · 500

Chạy thao tác xác thực: thao tác xác thực lỗi; kiểm tra luồng hiện có, không tự cho rằng phải xác thực lại.

Xử lý và thử lại: Truy vấn luồng xác thực hiện tại và xem có cần người dùng thao tác không. Không bắt đầu xác thực mới chỉ vì yêu cầu này lỗi; không gửi lại vào phiên hết hạn hoặc đã kết thúc.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 20010

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20010",
    "message": "Failed to run auth action"
  }
}

run_auth_action_failed · 20020 · 500

Kiểm tra account_id và dùng X-Api-Key của không gian làm việc sở hữu tài khoản. Khóa hiện tại không truy cập được tài khoản không tìm thấy trong không gian này.

Điều kiện: Áp dụng khi không tìm thấy tài khoản; giữ trạng thái HTTP và code của thao tác, dùng numeric_code để làm rõ tài khoản bị thiếu.

Xử lý và thử lại: Kiểm tra mã đích, chủ sở hữu tài nguyên và workspace hiện tại. Không coi đích đã xác nhận thiếu hoặc không truy cập được là lỗi dịch vụ tạm thời để tự thử lại.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

provider_adapter_not_found · 30004 · 502

Dịch vụ kênh chưa khả dụng. Kiểm tra trạng thái hoặc thử sau; xác nhận kết quả trước khi thử ghi lại.

Xử lý và thử lại: Truy vấn luồng xác thực hiện tại và xem có cần người dùng thao tác không. Không bắt đầu xác thực mới chỉ vì yêu cầu này lỗi; không gửi lại vào phiên hết hạn hoặc đã kết thúc.

JSON minh họa; message thay đổi theo nguyên nhân thực tế · 502 · 30004

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

provider_unavailable · 30002 · 502

Dịch vụ kênh chưa khả dụng. Kiểm tra trạng thái hoặc thử sau; xác nhận kết quả trước khi thử ghi lại.

Xử lý và thử lại: Truy vấn luồng xác thực hiện tại và xem có cần người dùng thao tác không. Không bắt đầu xác thực mới chỉ vì yêu cầu này lỗi; không gửi lại vào phiên hết hạn hoặc đã kết thúc.

Ví dụ · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}