Tham chiếu API

Tham chiếu

Tham chiếu mã lỗi

Đọc trạng thái HTTP, error.code và error.numeric_code theo thao tác hiện tại. Mã số chi tiết có thể phân biệt nguyên nhân mà giữ nguyên trạng thái HTTP và code. error.message dùng chẩn đoán, không rẽ nhánh chương trình; giữ request_id.

Định dạng phản hồi lỗi

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

request_id
Chuỗi bắt buộc do máy chủ tạo cho yêu cầu HTTP này, cũng có trong tiêu đề phản hồi X-Request-Id. Cung cấp giá trị này khi báo lỗi.
client_request_id
Chuỗi tùy chọn, chỉ phản chiếu nguyên giá trị X-Request-Id hợp lệ trong yêu cầu. Dùng để đối soát phía khách, không thay thế request_id của máy chủ.
error.code
Mã snake_case ổn định được giữ để tương thích; diễn giải cùng thao tác và trạng thái HTTP.
error.numeric_code
Chuỗi năm chữ số có thể làm rõ nguyên nhân mà không đổi code cũ hay trạng thái HTTP; không phải mã thao tác duy nhất toàn cục.
error.message
Thông báo chẩn đoán bằng tiếng Anh cho người đọc, có thể thay đổi theo nguyên nhân từ kênh. Không phân tích chuỗi này để rẽ nhánh chương trình.
JSON lỗi minh họa
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  },
  "client_request_id": "<CLIENT_REQUEST_ID>"
}

400 Bad Request

  • auth_mode_phone_required20019

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "auth_mode_phone_required",
        "numeric_code": "20019",
        "message": "Phone number is required for this auth mode"
      }
    }
    
  • create_api_key_failed11101

    Thao tác bị từ chối. Kiểm tra yêu cầu và giữ request_id.

    Xử lý và thử lại: Liệt kê hoặc truy vấn tài nguyên hiện có để xem lần tạo trước đã có hiệu lực chưa. Sửa nguyên nhân gốc và giữ request_id; không tự động tạo tài nguyên trùng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_api_key_failed",
        "numeric_code": "11101",
        "message": "Failed to create API key"
      }
    }
    
  • invalid_conversation_type37000

    type phải là user, group hoặc channel.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_conversation_type",
        "numeric_code": "37000",
        "message": "Field 'type' must be one of: user, group, channel"
      }
    }
    
  • invalid_provider30000

    Kiểm tra mã kênh trong URL.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_provider",
        "numeric_code": "30000",
        "message": "Invalid provider parameter"
      }
    }
    
  • invalid_reply_token36006

    Không đọc được mã trích dẫn. Sao chép nguyên data.message.reply_token từ sự kiện đế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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_reply_token",
        "numeric_code": "36006",
        "message": "Invalid or unreadable reply_token"
      }
    }
    
  • invalid_request10000

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_request",
        "numeric_code": "10000",
        "message": "Invalid request parameters"
      }
    }
    
  • invalid_target_workspace11003

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

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_target_workspace",
        "numeric_code": "11003",
        "message": "Invalid target workspace"
      }
    }
    
  • provider_invalid_request30001

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "provider_invalid_request",
        "numeric_code": "30001",
        "message": "Provider rejected the request"
      }
    }
    
  • rotate_api_key_failed11103

    Thao tác bị từ chối. Kiểm tra yêu cầu và giữ request_id.

    Xử lý và thử lại: Kiểm tra Key đích trong workspace hiện tại trước khi sửa hoặc xoay vòng. Thử lại không tạo lại Key đã thiếu. Nếu kết quả xoay vòng chưa rõ, xác nhận thông tin xác thực nào còn dùng được mà không lộ khóa.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "rotate_api_key_failed",
        "numeric_code": "11103",
        "message": "Failed to rotate API key"
      }
    }
    
  • unsupported_action30005

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unsupported_action",
        "numeric_code": "30005",
        "message": "Action not supported"
      }
    }
    
  • unsupported_conversation_type37001

    Kênh không hỗ trợ thao tác; chọn thao tác trong bảng 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unsupported_conversation_type",
        "numeric_code": "37001",
        "message": "Operation not supported for this conversation type"
      }
    }
    
  • unsupported_message_type36000

    Dùng message.type đượ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unsupported_message_type",
        "numeric_code": "36000",
        "message": "Message type not supported"
      }
    }
    
  • unsupported_provider_auth_mode20018

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unsupported_provider_auth_mode",
        "numeric_code": "20018",
        "message": "Auth mode not supported by this provider"
      }
    }
    
  • update_api_key_failed11102

    Thao tác bị từ chối. Kiểm tra yêu cầu và giữ request_id.

    Xử lý và thử lại: Kiểm tra Key đích trong workspace hiện tại trước khi sửa hoặc xoay vòng. Thử lại không tạo lại Key đã thiếu. Nếu kết quả xoay vòng chưa rõ, xác nhận thông tin xác thực nào còn dùng được mà không lộ khóa.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_api_key_failed",
        "numeric_code": "11102",
        "message": "Failed to update API key"
      }
    }
    
  • update_workspace_failed41001

    Thao tác bị từ chối. Kiểm tra yêu cầu và giữ request_id.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_workspace_failed",
        "numeric_code": "41001",
        "message": "Failed to update workspace"
      }
    }
    
  • wallet_invalid_request20021

    Kiểm tra tham số tạo tài khoản bằng ví và tiêu đề Idempotency-Key tùy chọ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_invalid_request",
        "numeric_code": "20021",
        "message": "Invalid wallet account request"
      }
    }
    

401 Unauthorized

  • invalid_api_key11001

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "invalid_api_key",
        "numeric_code": "11001",
        "message": "Invalid API key"
      }
    }
    
  • missing_api_key11000

    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.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "missing_api_key",
        "numeric_code": "11000",
        "message": "Missing X-Api-Key header"
      }
    }
    

403 Forbidden

  • beta_feature_not_enabled41002

    Không gian làm việc cần quyền thử nghiệm kín để dùng API cuộc gọi và đăng ký rõ các sự kiện cuộc gọi.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "beta_feature_not_enabled",
        "numeric_code": "41002",
        "message": "Beta feature not enabled"
      }
    }
    
  • cors_forbidden11009

    Nguồn, phương thức hoặc tiêu đề CORS không được phép. Kiểm tra môi trường gọi.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "cors_forbidden",
        "numeric_code": "11009",
        "message": "CORS preflight request is not allowed"
      }
    }
    
  • post_inaccessible39005

    Bài đăng và bình luận

    Kiểm tra tài khoản và các mã định danh đích mà API này thực sự yêu cầu. post_not_found xác nhận bài đăng không tồn tại. comment_not_found chỉ có nghĩa là không tìm thấy bình luận cấp đầu đích sau khi xác minh, không có nghĩa đã tìm mọi phản hồi. post_inaccessible nghĩa là không truy cập được, không chứng minh vắng mặt hay xác định nguyên nhân. Giữ lỗi và điều tra trước khi chọn bước tiếp theo.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "post_inaccessible",
        "numeric_code": "39005",
        "message": "Post is not accessible"
      }
    }
    
  • workspace_override_forbidden11002

    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.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "workspace_override_forbidden",
        "numeric_code": "11002",
        "message": "Workspace override is not allowed"
      }
    }
    

404 Not Found

  • account_not_found20020

    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.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "account_not_found",
        "numeric_code": "20020",
        "message": "Account not found"
      }
    }
    
  • account_operation_not_found20029

    Thao tác không tồn tại hoặc ngoài workspace này. Kiểm tra operation_id ban đầu và phạm vi API Key.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "account_operation_not_found",
        "numeric_code": "20029",
        "message": "Account operation not found"
      }
    }
    
  • call_not_found38003

    Cuộc gọi

    Không tìm thấy cuộc gọi trong tài khoản và không gian làm việc này.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "call_not_found",
        "numeric_code": "38003",
        "message": "Call not found"
      }
    }
    
  • comment_not_found39001

    Bài đăng và bình luận

    Kiểm tra tài khoản và các mã định danh đích mà API này thực sự yêu cầu. post_not_found xác nhận bài đăng không tồn tại. comment_not_found chỉ có nghĩa là không tìm thấy bình luận cấp đầu đích sau khi xác minh, không có nghĩa đã tìm mọi phản hồi. post_inaccessible nghĩa là không truy cập được, không chứng minh vắng mặt hay xác định nguyên nhân. Giữ lỗi và điều tra trước khi chọn bước tiếp theo.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "comment_not_found",
        "numeric_code": "39001",
        "message": "Comment not found"
      }
    }
    
  • contact_not_found35000

    Không tìm thấy liên hệ trong tài khoản này; kiểm tra mã định danh.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "contact_not_found",
        "numeric_code": "35000",
        "message": "Contact not found"
      }
    }
    
  • conversation_not_found37002

    Kênh không tìm thấy cuộc hội thoại; kiểm tra mã định danh và tài khoản.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "conversation_not_found",
        "numeric_code": "37002",
        "message": "Conversation not found"
      }
    }
    
  • group_not_found34004

    Không tìm thấy nhóm trong tài khoản này; kiểm tra ID nhóm.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "group_not_found",
        "numeric_code": "34004",
        "message": "Group not found"
      }
    }
    
  • not_found10001

    Kiểm tra đường dẫn API và phương thức HTTP.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "not_found",
        "numeric_code": "10001",
        "message": "Endpoint not found"
      }
    }
    
  • post_not_found39000

    Bài đăng và bình luận

    Kiểm tra tài khoản và các mã định danh đích mà API này thực sự yêu cầu. post_not_found xác nhận bài đăng không tồn tại. comment_not_found chỉ có nghĩa là không tìm thấy bình luận cấp đầu đích sau khi xác minh, không có nghĩa đã tìm mọi phản hồi. post_inaccessible nghĩa là không truy cập được, không chứng minh vắng mặt hay xác định nguyên nhân. Giữ lỗi và điều tra trước khi chọn bước tiếp theo.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "post_not_found",
        "numeric_code": "39000",
        "message": "Post not found"
      }
    }
    
  • target_workspace_not_found11004

    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.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "target_workspace_not_found",
        "numeric_code": "11004",
        "message": "Target workspace not found"
      }
    }
    

409 Conflict

  • account_allocation_busy20011

    Đang bận cấp tài khoản; thử lại sau một lú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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "account_allocation_busy",
        "numeric_code": "20011",
        "message": "Allocation is busy in the current region; please retry later"
      }
    }
    
  • account_already_authorized20016

    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.

    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ế
    {
      "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_found30006

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "account_binding_not_found",
        "numeric_code": "30006",
        "message": "Account is not bound to an available server"
      }
    }
    
  • account_webhook_already_exists40008

    Webhook Endpoint

    Dùng account_id để liệt kê các điểm nhận riêng của tài khoản và cập nhật điểm nhận active hiện có. Để chuyển, vô hiệu hóa điểm nhận active cũ trước rồi kích hoạt điểm nhận khác. Không tự động thử lại việc tạo hoặc kích hoạt lại.

    Xử lý và thử lại: Đọc cấu hình đầu nhận và phạm vi tài khoản trước khi gửi lại. PATCH thay thế thiết lập; giữ đủ đăng ký, chữ ký và chính sách thử lại cần dùng. Nếu xung đột đầu nhận active, cập nhật cái hiện có hoặc vô hiệu hóa nó trước khi bật cái khác.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "account_webhook_already_exists",
        "numeric_code": "40008",
        "message": "Account already has an active webhook endpoint"
      }
    }
    
  • billing_quote_changed20027

    Giá hoặc cơ sở tính đã đổi. Xác nhận kết quả ban đầu rồi lấy báo giá mới.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "billing_quote_changed",
        "numeric_code": "20027",
        "message": "Pricing changed; request a new quote"
      }
    }
    
  • billing_quote_expired20026

    Báo giá hết hạn. Kiểm tra kết quả tạo trước đó rồi lấy báo giá mới.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "billing_quote_expired",
        "numeric_code": "20026",
        "message": "Billing quote expired"
      }
    }
    
  • billing_quote_invalid20025

    Báo giá không khớp workspace hoặc yêu cầu. Xác nhận kết quả cũ rồi lấy báo giá phù hợp.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "billing_quote_invalid",
        "numeric_code": "20025",
        "message": "Billing quote does not match this request"
      }
    }
    
  • call_already_active38000

    Cuộc gọi

    Tài khoản đã có cuộc gọi đang hoạt động do hệ thống quản lý. Kiểm tra cuộc gọi đã biết và mục đích thao tác; lỗi này không yêu cầu gác cuộc gọi hay liên tục gọi lại cùng truy vấn lỗi.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "call_already_active",
        "numeric_code": "38000",
        "message": "Account already has an active call"
      }
    }
    
  • duplicate_provider_account20015

    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ế
    {
      "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"
      }
    }
    
  • no_allocatable_server20013

    Vùng chưa có tài nguyên trống; truy vấn vùng có thể cấp phát.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "no_allocatable_server",
        "numeric_code": "20013",
        "message": "No allocatable server in the current region"
      }
    }
    
  • provider_account_mismatch20017

    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ế
    {
      "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_ready30009

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "provider_not_ready",
        "numeric_code": "30009",
        "message": "Provider client is not ready"
      }
    }
    
  • wallet_account_creation_in_progress20030

    Workspace này đang tạo một tài khoản bằng ví khác. Hãy đợi hoàn tất rồi thử lại.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_account_creation_in_progress",
        "numeric_code": "20030",
        "message": "Account creation is in progress; please wait"
      }
    }
    
  • wallet_idempotency_conflict20024

    Khóa chống lặp đã gắn với tham số khác. Kiểm tra thao tác ban đầu trước khi tạo lại.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_idempotency_conflict",
        "numeric_code": "20024",
        "message": "Idempotency key was used for a different request"
      }
    }
    
  • wallet_insufficient_funds20023

    Số dư không đủ. Chủ sở hữu có thể nạp tiền rồi xác nhận yêu cầu ban đầu.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_insufficient_funds",
        "numeric_code": "20023",
        "message": "Insufficient wallet balance"
      }
    }
    
  • wallet_workspace_disabled20022

    Đã tắt mua mới bằng số dư; không có nghĩa thao tác hiện có đã bị hủy.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_workspace_disabled",
        "numeric_code": "20022",
        "message": "New wallet purchases are disabled"
      }
    }
    
  • workspace_account_quota_exceeded20014

    Đã đạt giới hạn tài khoản nhắn tin; kiểm tra mức sử dụng và hạn mứ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "workspace_account_quota_exceeded",
        "numeric_code": "20014",
        "message": "Workspace account quota exceeded"
      }
    }
    

422 Unprocessable Entity

  • contact_not_found35000

    GET /contacts/info trả về Conversation not found. Kiểm tra mã đích và tài khoản dùng để truy vấn.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "contact_not_found",
        "numeric_code": "35000",
        "message": "Conversation not found"
      }
    }
    

500 Internal Server Error

  • block_contact_failed35005

    Chặn liên hệ: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "block_contact_failed",
        "numeric_code": "35005",
        "message": "Failed to block contact"
      }
    }
    
  • call_control_failed38004

    Cuộc gọi

    Không thể truy vấn hoặc kết thúc cuộc gọi. Kiểm tra thao tác hiện tại và trạng thái cuộc gọi.

    Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "call_control_failed",
        "numeric_code": "38004",
        "message": "Failed to control call"
      }
    }
    
  • create_account_failed20002

    Tạo tài khoản: tạo tài nguyên lỗi hoặc chưa xác nhận được kết quả.

    Xử lý và thử lại: Liệt kê hoặc truy vấn tài nguyên hiện có để xem lần tạo trước đã có hiệu lực chưa. Sửa nguyên nhân gốc và giữ request_id; không tự động tạo tài nguyên trùng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_account_failed",
        "numeric_code": "20002",
        "message": "Failed to create account"
      }
    }
    
  • create_call_failed38002

    Cuộc gọi

    Tạo cuộc gọi: tạo tài nguyên lỗi hoặc chưa xác nhận được kết quả.

    Xử lý và thử lại: Liệt kê hoặc truy vấn tài nguyên hiện có để xem lần tạo trước đã có hiệu lực chưa. Sửa nguyên nhân gốc và giữ request_id; không tự động tạo tài nguyên trùng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_call_failed",
        "numeric_code": "38002",
        "message": "Failed to create call"
      }
    }
    
  • create_contact_failed35003

    Thêm liên hệ: tạo tài nguyên lỗi hoặc chưa xác nhận được kết quả.

    Xử lý và thử lại: Liệt kê hoặc truy vấn tài nguyên hiện có để xem lần tạo trước đã có hiệu lực chưa. Sửa nguyên nhân gốc và giữ request_id; không tự động tạo tài nguyên trùng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_contact_failed",
        "numeric_code": "35003",
        "message": "Failed to create contact"
      }
    }
    
  • create_group_failed34002

    Tạo nhóm: tạo tài nguyên lỗi hoặc chưa xác nhận được kết quả.

    Xử lý và thử lại: Liệt kê hoặc truy vấn tài nguyên hiện có để xem lần tạo trước đã có hiệu lực chưa. Sửa nguyên nhân gốc và giữ request_id; không tự động tạo tài nguyên trùng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_group_failed",
        "numeric_code": "34002",
        "message": "Failed to create group"
      }
    }
    
  • create_webhook_endpoint_failed40001

    Tạo điểm cuối Webhook: 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 cấu hình đầu nhận và phạm vi tài khoản trước khi gửi lại. PATCH thay thế thiết lập; giữ đủ đăng ký, chữ ký và chính sách thử lại cần dùng. Nếu xung đột đầu nhận active, cập nhật cái hiện có hoặc vô hiệu hóa nó trước khi bật cái khác.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "create_webhook_endpoint_failed",
        "numeric_code": "40001",
        "message": "Failed to create webhook endpoint"
      }
    }
    
  • deactivate_webhook_endpoint_failed40004

    Vô hiệu hoá điểm cuối Webhook: chưa xác nhận đã dừng hoặc vô hiệu hóa; xử lý tiếp phải giữ đúng mục tiêu dừng ban đầu.

    Xử lý và thử lại: Kiểm tra trạng thái để xác nhận đã dừng hoặc vô hiệu hóa chưa. Không khởi động hay kết nối lại tài nguyên vốn định dừng.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "deactivate_webhook_endpoint_failed",
        "numeric_code": "40004",
        "message": "Failed to deactivate webhook endpoint"
      }
    }
    
  • delete_account_failed20004

    Xoá tài khoản: chưa xác nhận được kết quả xóa.

    Xử lý và thử lại: Truy vấn tài nguyên để xác định đã xóa thành công chưa rồi quyết định có cần xóa lại không. Giữ request_id và xử lý phản hồi thành công theo tài liệu API này.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "delete_account_failed",
        "numeric_code": "20004",
        "message": "Failed to delete account"
      }
    }
    
  • delete_label_failed37014

    Xoá nhãn: chưa xác nhận được kết quả xóa.

    Xử lý và thử lại: Truy vấn tài nguyên để xác định đã xóa thành công chưa rồi quyết định có cần xóa lại không. Giữ request_id và xử lý phản hồi thành công theo tài liệu API này.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "delete_label_failed",
        "numeric_code": "37014",
        "message": "Failed to delete label"
      }
    }
    
  • delete_webhook_endpoint_failed40005

    Xoá điểm cuối Webhook: chưa xác nhận được kết quả xóa.

    Xử lý và thử lại: Truy vấn tài nguyên để xác định đã xóa thành công chưa rồi quyết định có cần xóa lại không. Giữ request_id và xử lý phản hồi thành công theo tài liệu API này.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "delete_webhook_endpoint_failed",
        "numeric_code": "40005",
        "message": "Failed to delete webhook endpoint"
      }
    }
    
  • edit_message_failed36005

    Sửa tin nhắ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "edit_message_failed",
        "numeric_code": "36005",
        "message": "Failed to edit message"
      }
    }
    
  • get_account_failed20001

    Lấy tài khoản: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_account_failed",
        "numeric_code": "20001",
        "message": "Failed to get account"
      }
    }
    
  • get_auth_state_failed20006

    Trạng thái xác thực: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_auth_state_failed",
        "numeric_code": "20006",
        "message": "Failed to get account auth state"
      }
    }
    
  • get_contact_failed35002

    Lấy liên hệ: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_contact_failed",
        "numeric_code": "35002",
        "message": "Failed to get contact"
      }
    }
    
  • get_contact_membership_failed35004

    Kiểm tra trạng thái liên hệ: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_contact_membership_failed",
        "numeric_code": "35004",
        "message": "Failed to get contact membership"
      }
    }
    
  • get_conversation_failed37004

    Chi tiết hội thoại: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_conversation_failed",
        "numeric_code": "37004",
        "message": "Failed to get conversation"
      }
    }
    
  • get_group_failed34001

    Lấy chi tiết nhóm: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_group_failed",
        "numeric_code": "34001",
        "message": "Failed to get group"
      }
    }
    
  • get_group_invite_code_failed34010

    Lấy liên kết mời nhóm: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_group_invite_code_failed",
        "numeric_code": "34010",
        "message": "Failed to get group invite code"
      }
    }
    
  • get_session_failed20005

    Đọc phiên tài khoản hiện tại: dịch vụ không tải được phiên hiện tại.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_session_failed",
        "numeric_code": "20005",
        "message": "Failed to get account session"
      }
    }
    
  • get_webhook_endpoint_failed40002

    Lấy điểm cuối Webhook: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_webhook_endpoint_failed",
        "numeric_code": "40002",
        "message": "Failed to get webhook endpoint"
      }
    }
    
  • get_workspace_failed41000

    Lấy workspace hiện tại: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_workspace_failed",
        "numeric_code": "41000",
        "message": "Failed to get workspace"
      }
    }
    
  • leave_group_failed34003

    Rời nhóm: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "leave_group_failed",
        "numeric_code": "34003",
        "message": "Failed to leave group"
      }
    }
    
  • list_accounts_failed20000

    Liệt kê tài khoản: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_accounts_failed",
        "numeric_code": "20000",
        "message": "Failed to list accounts"
      }
    }
    
  • list_api_keys_failed11100

    Liệt kê API key: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_api_keys_failed",
        "numeric_code": "11100",
        "message": "Failed to list API keys"
      }
    }
    
  • list_blocklist_failed35007

    Lấy danh sách chặn: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_blocklist_failed",
        "numeric_code": "35007",
        "message": "Failed to list blocklist"
      }
    }
    
  • list_contacts_failed35001

    Liệt kê liên hệ: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_contacts_failed",
        "numeric_code": "35001",
        "message": "Failed to list contacts"
      }
    }
    
  • list_conversation_labels_failed37012

    Liệt kê nhãn hội thoại: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_conversation_labels_failed",
        "numeric_code": "37012",
        "message": "Failed to list conversation labels"
      }
    }
    
  • list_conversation_members_failed37005

    Liệt kê thành viên: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_conversation_members_failed",
        "numeric_code": "37005",
        "message": "Failed to list conversation members"
      }
    }
    
  • list_conversations_failed37003

    Liệt kê hội thoại: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_conversations_failed",
        "numeric_code": "37003",
        "message": "Failed to list conversations"
      }
    }
    
  • list_group_join_requests_failed34007

    Danh sách yêu cầu vào nhóm: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_group_join_requests_failed",
        "numeric_code": "34007",
        "message": "Failed to list group join requests"
      }
    }
    
  • list_groups_failed34000

    Liệt kê nhóm: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_groups_failed",
        "numeric_code": "34000",
        "message": "Failed to list groups"
      }
    }
    
  • list_provider_regions_failed30011

    Liệt kê khu vực của nhà cung cấp: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_provider_regions_failed",
        "numeric_code": "30011",
        "message": "Failed to list provider regions"
      }
    }
    
  • list_webhook_endpoints_failed40000

    Liệt kê điểm cuối Webhook: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_webhook_endpoints_failed",
        "numeric_code": "40000",
        "message": "Failed to list webhook endpoints"
      }
    }
    
  • mark_conversation_read_failed37006

    Đánh dấu hội thoại đã đọc: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "mark_conversation_read_failed",
        "numeric_code": "37006",
        "message": "Failed to mark conversation as read"
      }
    }
    
  • mark_conversation_unread_failed37007

    Đánh dấu hội thoại chưa đọc: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "mark_conversation_unread_failed",
        "numeric_code": "37007",
        "message": "Failed to mark conversation as unread"
      }
    }
    
  • mute_conversation_failed37008

    Tắt thông báo hội thoại: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "mute_conversation_failed",
        "numeric_code": "37008",
        "message": "Failed to mute conversation"
      }
    }
    
  • pin_conversation_failed37010

    Ghim hội thoại: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "pin_conversation_failed",
        "numeric_code": "37010",
        "message": "Failed to pin conversation"
      }
    }
    
  • pin_message_failed36002

    Ghim / bỏ ghim tin nhắ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "pin_message_failed",
        "numeric_code": "36002",
        "message": "Failed to pin message"
      }
    }
    
  • react_message_failed36004

    Thả cảm xúc vào tin nhắ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "react_message_failed",
        "numeric_code": "36004",
        "message": "Failed to react to message"
      }
    }
    
  • request_conversation_history_failed37016

    Yêu cầu truy xuất lịch sử hội thoại: 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: Kiểm tra cuộc trò chuyện riêng WhatsApp và mốc before. request_id chỉ dùng chẩn đoán HTTP. Sự kiện lịch sử có thể đến sau khi HTTP hết giờ; không tự thử lại hoặc coi không có sự kiện, lô rỗng hay lô ngắn là hoàn tất.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "request_conversation_history_failed",
        "numeric_code": "37016",
        "message": "Failed to request conversation history"
      }
    }
    
  • revoke_message_failed36003

    Thu hồi tin nhắ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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "revoke_message_failed",
        "numeric_code": "36003",
        "message": "Failed to revoke message"
      }
    }
    
  • run_action_failed20007

    Chạy thao tác 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "run_action_failed",
        "numeric_code": "20007",
        "message": "Failed to run account action"
      }
    }
    
  • run_auth_action_failed20010

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "run_auth_action_failed",
        "numeric_code": "20010",
        "message": "Failed to run auth action"
      }
    }
    
  • run_runtime_action_failed20008

    Thay đổi runtime: thao tác runtime lỗi; riêng phản hồi này chưa xác nhận trạng thái kết nối cuối cùng.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "run_runtime_action_failed",
        "numeric_code": "20008",
        "message": "Failed to run runtime action"
      }
    }
    
  • run_session_action_failed20009

    Chạy thao tác phiên: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "run_session_action_failed",
        "numeric_code": "20009",
        "message": "Failed to run session action"
      }
    }
    
  • send_message_failed36001

    Gửi tin nhắn thất bại hoặc chưa thể xác nhận kết quả.

    Xử lý và thử lại: Trước khi gửi lại, xác nhận tin nhắn hoặc phản hồi gốc đã được tạo chưa. Hết giờ hoặc phản hồi lỗi có thể khiến kết quả chưa rõ; truy vấn sau không thấy phản hồi cũng không chứng minh chưa ghi. Không tự động gửi lại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "send_message_failed",
        "numeric_code": "36001",
        "message": "Failed to send message"
      }
    }
    
  • set_contact_note_failed35008

    Đặt ghi chú liên hệ: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "set_contact_note_failed",
        "numeric_code": "35008",
        "message": "Failed to set contact note"
      }
    }
    
  • set_group_join_approval_mode_failed34009

    Đặt chế độ duyệt vào nhóm: thay đổi nhóm lỗi; có thể do kênh từ chối hoặc thiếu quyền quản trị cần thiết.

    Xử lý và thử lại: Kiểm tra nhóm, tư cách thành viên, quyền quản trị cần thiết và kết quả hiện tại. Giải quyết vấn đề truy cập/quyền trước khi sửa lại; kết quả ghi chưa rõ phải được đối soát trước.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "set_group_join_approval_mode_failed",
        "numeric_code": "34009",
        "message": "Failed to set group join approval mode"
      }
    }
    
  • set_label_members_failed37015

    Thêm / gỡ nhãn trên hội thoại: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "set_label_members_failed",
        "numeric_code": "37015",
        "message": "Failed to set label members"
      }
    }
    
  • unblock_contact_failed35006

    Bỏ chặn liên hệ: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unblock_contact_failed",
        "numeric_code": "35006",
        "message": "Failed to unblock contact"
      }
    }
    
  • unmute_conversation_failed37009

    Bật thông báo hội thoại: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unmute_conversation_failed",
        "numeric_code": "37009",
        "message": "Failed to unmute conversation"
      }
    }
    
  • unpin_conversation_failed37011

    Bỏ ghim hội thoại: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unpin_conversation_failed",
        "numeric_code": "37011",
        "message": "Failed to unpin conversation"
      }
    }
    
  • update_account_failed20003

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_account_failed",
        "numeric_code": "20003",
        "message": "Failed to update account"
      }
    }
    
  • update_group_info_failed34006

    Cập nhật thông tin nhóm: thay đổi nhóm lỗi; có thể do kênh từ chối hoặc thiếu quyền quản trị cần thiết.

    Xử lý và thử lại: Kiểm tra nhóm, tư cách thành viên, quyền quản trị cần thiết và kết quả hiện tại. Giải quyết vấn đề truy cập/quyền trước khi sửa lại; kết quả ghi chưa rõ phải được đối soát trước.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_group_info_failed",
        "numeric_code": "34006",
        "message": "Failed to update group info"
      }
    }
    
  • update_group_join_requests_failed34008

    Duyệt / từ chối yêu cầu vào nhóm: thay đổi nhóm lỗi; có thể do kênh từ chối hoặc thiếu quyền quản trị cần thiết.

    Xử lý và thử lại: Kiểm tra nhóm, tư cách thành viên, quyền quản trị cần thiết và kết quả hiện tại. Giải quyết vấn đề truy cập/quyền trước khi sửa lại; kết quả ghi chưa rõ phải được đối soát trước.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_group_join_requests_failed",
        "numeric_code": "34008",
        "message": "Failed to update group join requests"
      }
    }
    
  • update_group_members_failed34005

    Cập nhật thành viên nhóm: thay đổi nhóm lỗi; có thể do kênh từ chối hoặc thiếu quyền quản trị cần thiết.

    Xử lý và thử lại: Kiểm tra nhóm, tư cách thành viên, quyền quản trị cần thiết và kết quả hiện tại. Giải quyết vấn đề truy cập/quyền trước khi sửa lại; kết quả ghi chưa rõ phải được đối soát trước.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_group_members_failed",
        "numeric_code": "34005",
        "message": "Failed to update group members"
      }
    }
    
  • update_webhook_endpoint_failed40003

    Cập nhật điểm cuối Webhook: 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 cấu hình đầu nhận và phạm vi tài khoản trước khi gửi lại. PATCH thay thế thiết lập; giữ đủ đăng ký, chữ ký và chính sách thử lại cần dùng. Nếu xung đột đầu nhận active, cập nhật cái hiện có hoặc vô hiệu hóa nó trước khi bật cái khác.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "update_webhook_endpoint_failed",
        "numeric_code": "40003",
        "message": "Failed to update webhook endpoint"
      }
    }
    
  • upsert_label_failed37013

    Tạo hoặc cập nhật nhã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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "upsert_label_failed",
        "numeric_code": "37013",
        "message": "Failed to upsert label"
      }
    }
    

501 Not Implemented

  • unsupported_by_provider30003

    Kênh không hỗ trợ thao tác; chọn thao tác trong bảng 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "unsupported_by_provider",
        "numeric_code": "30003",
        "message": "Operation not supported by this provider"
      }
    }
    

502 Bad Gateway

  • get_post_failed39006

    Bài đăng và bình luận

    Lấy bài đăng của tài khoản: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "get_post_failed",
        "numeric_code": "39006",
        "message": "Failed to get post"
      }
    }
    
  • list_post_comments_failed39003

    Bài đăng và bình luận

    Liệt kê bình luận cấp đầu: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_post_comments_failed",
        "numeric_code": "39003",
        "message": "Failed to list post comments"
      }
    }
    
  • list_posts_failed39002

    Bài đăng và bình luận

    Liệt kê bài đăng của tài khoản: dịch vụ không tạo được kết quả truy vấn hợp lệ.

    Xử lý và thử lại: Giữ request_id, kiểm tra mã định danh và quyền truy cập của tài khoản. Chỉ thử đọc lại sau khi kiểm tra nguyên nhân; truy vấn thất bại không chứng minh dữ liệu rỗng hay không tồn tại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "list_posts_failed",
        "numeric_code": "39002",
        "message": "Failed to list posts"
      }
    }
    
  • provider_adapter_not_found30004

    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: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "provider_adapter_not_found",
        "numeric_code": "30004",
        "message": "Provider adapter unavailable"
      }
    }
    
  • provider_unavailable30002

    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: 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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "provider_unavailable",
        "numeric_code": "30002",
        "message": "Provider service unavailable"
      }
    }
    
  • reply_post_comment_failed39004

    Bài đăng và bình luận

    Kiểm tra bài đăng, bình luận cấp đầu đã xác nhận và phân loại lỗi. Nếu kết quả ghi chưa rõ, giữ request_id và điều tra trước khi gửi lại. Thiếu phản hồi ở lần đọc sau chưa đủ để quyết định thử lại.

    Xử lý và thử lại: Trước khi gửi lại, xác nhận tin nhắn hoặc phản hồi gốc đã được tạo chưa. Hết giờ hoặc phản hồi lỗi có thể khiến kết quả chưa rõ; truy vấn sau không thấy phản hồi cũng không chứng minh chưa ghi. Không tự động gửi lại.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "reply_post_comment_failed",
        "numeric_code": "39004",
        "message": "Failed to confirm comment reply; result may be unknown, do not automatically retry"
      }
    }
    

503 Service Unavailable

  • allocation_service_unavailable20012

    Dịch vụ cấp tài khoản tạm không khả dụng; thử lại sau.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "allocation_service_unavailable",
        "numeric_code": "20012",
        "message": "Allocation service is temporarily unavailable"
      }
    }
    
  • call_service_unavailable38001

    Cuộc gọi

    Dịch vụ cuộc gọi không khả dụng. Kiểm tra kết nối và cấu hình Provider/Gateway.

    Xử lý và thử lại: Trước khi tạo hoặc kết thúc cuộc gọi, truy vấn cuộc gọi đang được quản lý cùng call_id/state. preparing chưa phải quay số hay được trả lời; ended và failed đều là trạng thái kết thúc. Không gác lại chỉ vì failed.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "call_service_unavailable",
        "numeric_code": "38001",
        "message": "Call service unavailable"
      }
    }
    
  • internal_auth_not_configured11006

    Dịch vụ phiên xác thực cần cho yêu cầu này chưa khả dụng hoặc chưa cấu hình. Liên hệ đơn vị vận hành để kiểm tra dịch vụ phiên 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.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "request_id": "req_example",
      "error": {
        "code": "internal_auth_not_configured",
        "numeric_code": "11006",
        "message": "Internal endpoint authentication is not configured"
      }
    }
    
  • wallet_unavailable20028

    Dữ liệu hoặc cấu hình ví tạm không khả dụng. Kết quả ghi có thể chưa rõ; kiểm tra thao tác ban đầu.

    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ế
    {
      "request_id": "req_example",
      "error": {
        "code": "wallet_unavailable",
        "numeric_code": "20028",
        "message": "Wallet service is unavailable"
      }
    }
    

Nguyên nhân chi tiết theo mã số

Các nguyên nhân này giữ nguyên trạng thái HTTP và code của thao tác. Xem tổ hợp áp dụng trong bảng lỗi từng API; không phải nguyên nhân nào cũng áp dụng cho mọi thao tác hoặc kênh.

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.

Sự kiện lỗi tài khoản

Một số sự kiện WhatsApp account.auth.failed có đối tượng data.error tùy chọn, với code, numeric_code và message là chuỗi không rỗng. Đọc trong sự kiện và xử lý riêng với phản hồi lỗi HTTP.

Sự kiện cũ hoặc ngoài phạm vi có thể không có data.error. Giữ tương thích last_error; mã thiếu hoặc lạ dùng quy trình lỗi tài khoản hiện có. Danh sách và chi tiết tài khoản không được thêm đối tượng này. Phân loại này không xác nhận khóa vĩnh viễn hay thời hạn khôi phục.

Sau khi tiếp nhận an toàn và chấp nhận xử lý, vẫn trả 2xx để xác nhận giao. Lỗi tài khoản khác lỗi giao HTTP; không từ chối webhook chỉ vì tài khoản lỗi và gây giao lại. Quy tắc thử lại/phát lại cũ vẫn áp dụng, không bổ sung lỗi cho sự kiện lịch sử.

  • account_auth_failed20100

    Xác thực tài khoản thất bại nhưng chưa xác định nguyên nhân cụ thể. Dùng luồng lỗi hiện có, không tự suy ra bị hạn chế hay đăng xuất.

    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ế
    {
      "id": "<EVENT_ID>",
      "type": "account.auth.failed",
      "provider": "whatsapp",
      "account_id": "<ACCOUNT_ID>",
      "occurred_at": "2026-10-16T00:00:00Z",
      "data": {
        "auth_status": "failed",
        "runtime_status": "disconnected",
        "event": {
          "kind": "account_auth_status",
          "auth_status": "failed",
          "runtime_status": "disconnected"
        },
        "error": {
          "code": "account_auth_failed",
          "numeric_code": "20100",
          "message": "Account authentication failed. The specific cause could not be determined."
        }
      }
    }
    
  • account_logged_out20101

    Phiên tài khoản hiện tại không còn hiệu lực. Hướng dẫn người dùng xác thực lại theo luồng kênh hỗ trợ.

    Xử lý và thử lại: Hướng dẫn người dùng xác thực lại qua luồng kênh hỗ trợ. Sau đó kiểm tra runtime và xác nhận kết nối sẵn sàng trước khi tiếp tục thao tác cần kết nối.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "id": "<EVENT_ID>",
      "type": "account.auth.failed",
      "provider": "whatsapp",
      "account_id": "<ACCOUNT_ID>",
      "occurred_at": "2026-10-16T00:00:00Z",
      "data": {
        "auth_status": "failed",
        "runtime_status": "disconnected",
        "event": {
          "kind": "account_auth_status",
          "auth_status": "failed",
          "runtime_status": "disconnected"
        },
        "error": {
          "code": "account_logged_out",
          "numeric_code": "20101",
          "message": "The account session is no longer valid. Reauthorization is required."
        }
      }
    }
    
  • account_restricted20102

    Sự kiện WhatsApp account.auth.failed này xác định hạn chế đăng nhập hiện tại qua data.error.code=account_restricted và numeric_code=20102. Không xác nhận khóa vĩnh viễn hay thời điểm khôi phục.

    Xử lý và thử lại: Dừng gửi và thử lại tự động, hướng dẫn người dùng kiểm tra và xử lý hạn chế trong ứng dụng WhatsApp chính thức. Chỉ tiếp tục sau khi giải quyết và xác thực lại nếu cần; trạng thái running trước đó không chứng minh hạn chế đã hết.

    JSON minh họa; message thay đổi theo nguyên nhân thực tế
    {
      "id": "<EVENT_ID>",
      "type": "account.auth.failed",
      "provider": "whatsapp",
      "account_id": "<ACCOUNT_ID>",
      "occurred_at": "2026-10-16T00:00:00Z",
      "data": {
        "auth_status": "failed",
        "runtime_status": "disconnected",
        "event": {
          "kind": "account_auth_status",
          "auth_status": "failed",
          "runtime_status": "disconnected"
        },
        "error": {
          "code": "account_restricted",
          "numeric_code": "20102",
          "message": "Account login is restricted. Check the official WhatsApp app for details."
        }
      }
    }