Gửi tin nhắn văn bả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ụ.

invalid_reply_token · 36006 · 400

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ế · 400 · 36006

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_reply_token",
    "numeric_code": "36006",
    "message": "Invalid or unreadable reply_token"
  }
}

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.

Ví dụ · 400 · 10000

{
  "request_id": "req_message_invalid_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid message request body"
  }
}

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.

Ví dụ · 400 · 30001

{
  "request_id": "req_sticker_rejected_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "sticker upload failed: media is unsupported"
  }
}

provider_invalid_request · 36007 · 400

Tài nguyên nhãn dán không qua kiểm tra trước khi gọi gửi đến kênh. Phản hồi có thể nêu lý do chuẩn bị cụ thể; numeric_code=36007 không có nghĩa đã thử gửi.

Điều kiện: Áp dụng khi tài nguyên nhãn dán hoặc URL bị từ chối trong bước kiểm tra trước khi gửi đến kênh.

Xử lý và thử lại: Sửa lỗi tài nguyên nhãn dán được báo rồi mới gửi lại. Phân loại này xuất hiện lúc chuẩn bị nội dung, trước khi gọi gửi đến kênh; không được mô tả là đã có thể gửi nhưng chưa rõ kết quả.

Ví dụ · 400 · 36007

{
  "request_id": "req_sticker_invalid_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "36007",
    "message": "invalid sticker media: invalid WebP container length"
  }
}

unsupported_message_type · 36000 · 400

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ế · 400 · 36000

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_message_type",
    "numeric_code": "36000",
    "message": "Message type 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_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"
  }
}

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 · 30014 · 409

Thiếu phiên bản chạy của kênh mà tài khoản cần. Đây là vấn đề khả dụng runtime, không chứng minh xác thực đã hết hạn.

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

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}

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

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

send_message_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: Áp dụng khi kênh không cung cấp phân loại lỗi cụ thể hơn; giữ nguyên lỗi của thao tác hiện tạ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.

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": "send_message_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

send_message_failed · 36001 · 500

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.

Ví dụ · 500 · 36001

{
  "request_id": "req_sticker_prepare_failed_example",
  "error": {
    "code": "send_message_failed",
    "numeric_code": "36001",
    "message": "download sticker: media download returned HTTP 503"
  }
}

unsupported_by_provider · 30003 · 501

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.

Ví dụ · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

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: 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ế · 502 · 30004

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

provider_unavailable · 20102 · 502

Gửi tin WhatsApp đồng bộ phát hiện hạn chế đăng nhập: HTTP 502, provider_unavailable, 20102. Cùng ý nghĩa mã số có thể xuất hiện dưới account_restricted trong sự kiện lỗi WhatsApp. Phản hồi HTTP này không tự đổi trạng thái tài khoản hay tạo thêm sự kiện.

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.

Kênh áp dụng: WhatsApp

Ví dụ · 502 · 20102

{
  "request_id": "req_example_whatsapp_account_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "20102",
    "message": "Account login is restricted. Check the official WhatsApp app for details."
  }
}

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: 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.

Ví dụ · 502 · 30002

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

provider_unavailable · 30010 · 502

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.

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.

Kênh áp dụng: WhatsApp

Ví dụ · 502 · 30010

{
  "request_id": "req_example_message_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}

provider_unavailable · 30019 · 502

Nền tảng hạn chế rõ ràng việc gửi tin này: HTTP 502, provider_unavailable, 30019. Không xác nhận tài khoản bị khóa vĩnh viễn hay có thời điểm gỡ hạn cố định.

Xử lý và thử lại: Dừng tự thử lại với hạn chế gửi tin này. Chỉ gửi tiếp sau khi xác nhận nền tảng đã gỡ hạn; không có thời gian cố định và lỗi này không tự yêu cầu xác thực lại.

Kênh áp dụng: WhatsApp

Ví dụ · 502 · 30019

{
  "request_id": "req_example_message_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30019",
    "message": "Message sending is restricted by the platform"
  }
}

provider_unavailable · 30020 · 502

Yêu cầu đồng bộ whatsapp-protocol xác định hạn chế đăng nhập qua numeric_code=30020. Có thể ảnh hưởng nhập phiên, runtime, gửi và truy vấn liên hệ, đồng thời giữ trạng thái HTTP và code của thao tác. Không áp dụng hợp đồng sự kiện WhatsApp 20102 cho kênh này.

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.

Kênh áp dụng: WhatsApp Protocol

Ví dụ · 502 · 30020

{
  "request_id": "req_example_account_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30020",
    "message": "Account login is restricted. Check the official WhatsApp app for details."
  }
}

provider_unavailable · 30021 · 502

WhatsApp chưa kết nối khi chạy thao tác; giữ nguyên thông báo kết nối gốc. Điều này không chứng minh đã đăng xuất hay hết xác thực, cũng không tự kết nối lại, gửi lại hoặc đổi trạng thái tài khoản.

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

Ví dụ · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}

provider_unavailable · 34012 · 502

Tài khoản cần quyền quản trị viên để gửi vào nhóm WhatsApp này. Hãy cập nhật vai trò trong nhóm trước khi thử lại; đừng gửi lại yêu cầu chưa đổ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.

Kênh áp dụng: WhatsApp

Ví dụ · 502 · 34012

{
  "request_id": "req_example_group_admin_required",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "34012",
    "message": "Group administrator privileges are required to send messages to this group"
  }
}