Cập nhật tài khoản

Đọ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ụ.

auth_mode_phone_required · 20019 · 400

Cách ủy quyền này yêu cầu provider_data.phone khi tạo tài khoản.

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 · 20019

{
  "request_id": "req_example",
  "error": {
    "code": "auth_mode_phone_required",
    "numeric_code": "20019",
    "message": "Phone number is required for this auth mode"
  }
}

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"
  }
}

unsupported_provider_auth_mode · 20018 · 400

Dùng auth_mode được kênh hỗ trợ.

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 · 20018

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_provider_auth_mode",
    "numeric_code": "20018",
    "message": "Auth mode not supported by this provider"
  }
}

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"
  }
}

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_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"
  }
}

provider_not_ready · 30015 · 409

Runtime của kênh đã dừng. Kiểm tra có chủ ý không trước khi khởi động; runtime dừng không tự đồng nghĩa đã đăng xuất.

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.

Kênh áp dụng: WhatsApp

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

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}

egress_change_not_supported · 20034 · 422

Tài khoản dùng mạng mặc định cố định; không thể đổi vùng hoặc kênh bằng thao tác cập nhật tài khoản thông thường.

Đ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: 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ế · 422 · 20034

{
  "request_id": "req_example",
  "error": {
    "code": "egress_change_not_supported",
    "numeric_code": "20034",
    "message": "The requested network change is not supported"
  }
}

update_account_failed · 20003 · 500

Cập nhật tài khoản: lỗi chưa phân loại làm gián đoạn thay đổi; cần xác nhận trạng thái tài nguyên cuối cùng.

Xử lý và thử lại: Đọc trạng thái hiện tại và xác nhận kết quả lần thay đổi trước khi thử lại. Giữ request_id; không tự động ghi lại khi kết quả chưa rõ.

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

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20003",
    "message": "Failed to update account"
  }
}

update_account_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": "update_account_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

update_account_failed · 30010 · 500

Kênh không hoàn thành được thao tác. message có thể kèm nguyên nhân gốc sau “Provider operation failed:”; nội dung này thay đổi và không phải giao diện lập trình ổn định.

Điều kiện: Chỉ áp dụng khi thực sự đổi chế độ xác thực và gọi đăng xuất WhatsApp. Cập nhật thông tin tài khoản thông thường không tạo ra mã số chi tiết này.

Xử lý và thử lại: Đọc trạng thái hiện tại và xác nhận kết quả lần thay đổi trước khi thử lại. Giữ request_id; không tự động ghi lại khi kết quả chưa rõ.

Kênh áp dụng: WhatsApp

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

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

update_account_failed · 30021 · 500

Tại thời điểm yêu cầu này, tài khoản chưa kết nối với nền tảng nhắn tin. Thêm liên hệ WhatsApp có thể trả về 500 / create_contact_failed / 30021. Điều này không chứng minh tài khoản đã đăng xuất hoặc trạng thái hiện tại vẫn là disconnected; hãy truy vấn trạng thái hiện tại trước khi chọn cách khôi phục.

Điều kiện: Chỉ áp dụng khi thực sự đổi chế độ xác thực và gọi đăng xuất WhatsApp. Cập nhật thông tin tài khoản thông thường không tạo ra mã số chi tiết này.

Xử lý và thử lại: Tạm dừng thao tác cần kết nối. Trước tiên gọi POST /v1/accounts/{account_id}/runtime/refresh, khôi phục theo trạng thái mới nhất rồi xác nhận runtime_status=running trước yêu cầu nghiệp vụ. Xác nhận kết quả ghi trước khi gửi lại.

Kênh áp dụng: WhatsApp

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

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

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: Đọc trạng thái hiện tại và xác nhận kết quả lần thay đổi trước khi thử lại. Giữ request_id; không tự động ghi lại khi kết quả chưa rõ.

Ví dụ · 502 · 30002

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