Thêm liên hệ

Đọ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_request · 10000 · 400

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

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

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

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

invalid_target_workspace · 11003 · 400

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

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

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

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

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

provider_invalid_request · 30001 · 400

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

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

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

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

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

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

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

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

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

create_contact_failed · 30017 · 500

Kênh thượng nguồn từ chối rõ ràng do tần suất yêu cầu quá cao. Phân loại số này giữ nguyên trạng thái HTTP và code cũ của thao tác.

Xử lý và thử lại: Tạm dừng yêu cầu, thử lại sau theo chính sách có giới hạn số lần. Không cam kết thời gian chờ cố định hay xử lý Retry-After ở đây. Xác nhận kết quả cũ trước khi ghi lại.

Kênh áp dụng: WhatsApp

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

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30017",
    "message": "Provider rate limit exceeded"
  }
}

create_contact_failed · 30018 · 500

Trạng thái nền App State của tài khoản trên kênh bị lệch đồng bộ. Đây là vấn đề đồng bộ tài khoản, không phải lỗi định dạng yêu cầu chung.

Xử lý và thử lại: Chờ kênh khôi phục trạng thái nền App State của tài khoản, rồi kiểm tra trạng thái trước khi thử lại. Không suy ra thông tin xác thực hết hiệu lực hay bắt đầu xác thực lại chỉ từ phân loại này.

Kênh áp dụng: WhatsApp

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

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "30018",
    "message": "Provider app state is out of sync"
  }
}

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

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": "create_contact_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

create_contact_failed · 35003 · 500

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ế · 500 · 35003

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35003",
    "message": "Failed to create contact"
  }
}

create_contact_failed · 35009 · 500

Trong lần tra cứu này, WhatsApp không nhận diện số đích là liên hệ đang hoạt động. Điều này không chứng minh số chưa đăng ký hoặc không thể sử dụng vĩnh viễn.

Xử lý và thử lại: Xác nhận mã quốc gia, số điện thoại và trạng thái đăng ký WhatsApp với người dùng, đồng thời xem error.message. Chỉ yêu cầu lại sau khi kiểm tra nguyên nhân; không tự động thử lại cùng số liên tục.

Kênh áp dụng: WhatsApp

Ví dụ · 500 · 35009

{
  "request_id": "req_example_contact_not_active",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35009",
    "message": "Target phone number was not recognized as an active WhatsApp contact"
  }
}

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

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

provider_unavailable · 30002 · 502

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

Xử lý và thử lại: 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.

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

Kênh áp dụng: WhatsApp

Ví dụ · 502 · 30010

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

provider_unavailable · 30021 · 502

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.

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