Lỗi API

Mọi lệnh gọi thất bại đến REST API của ReputeCast đều trả về một problem document theo RFC 9457: các lỗi API RFC 9457 bên dưới dùng chung một cấu trúc JSON, được trả về dưới dạng application/problem+json, kèm một code cố định để chương trình của bạn rẽ nhánh. Định dạng này được định nghĩa trong RFC 9457 (kiểm tra tháng 10/2026).

Các trường của problem document

Trường	Kiểu	Ý nghĩa
status	integer	Mã trạng thái HTTP, giống với mã của phản hồi.
title	string	Văn bản trạng thái HTTP, chẳng hạn Forbidden.
detail	string	Một câu giúp người đọc biết cần làm gì. Câu này có thể thay đổi giữa các phiên bản và có thể bằng tiếng Việt, vì vậy hãy hiển thị nó, đừng phân tích nó.
code	string	Mã cố định để máy đọc, chẳng hạn permission_denied. Xem mã lỗi.
permission	string	Khóa quyền còn thiếu, có trên permission_denied và trên escalation_denied khi thiếu đúng một quyền.
helpers	string[]	Tối đa hai thành viên đang có quyền còn thiếu, để người dùng biết nên hỏi ai.
errors	object[]	Với yêu cầu không hợp lệ: mỗi vấn đề một mục, gồm message, location (chẳng hạn body.email hoặc query.pageSize) và value.
meta	object	Thông tin thêm cho một số mã, ví dụ lockedUntil và failures trên locked, attemptsLeft trên các lỗi đăng nhập, retryAfter trên giới hạn tốc độ của cửa hàng, rules trên approval_required.

type và instance thuộc mô hình RFC 9457 nhưng ReputeCast không dùng. Khi không có type, loại lỗi là about:blank, nghĩa là trạng thái HTTP đã nói lên tất cả. Một vài lỗi do framework tự tạo ra, chẳng hạn lỗi máy chủ, không có code: với những lỗi đó, hãy dùng status.

Đường dẫn không tồn tại dưới /api/ trả về 404 với mã not_found và detail “No such API endpoint.”

Ví dụ body

Thiếu quyền

Khóa hoặc thành viên không có quyền mà một thao tác cần sẽ nhận 403. Quyền đó và tối đa hai thành viên đang có quyền nằm trong body:

403 Forbidden

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Sending needs the campaigns:send permission. Ask Marcus Chen or Linh Nguyen.",
  "code": "permission_denied",
  "permission": "campaigns:send",
  "helpers": ["Marcus Chen", "Linh Nguyen"]
}

Hãy tạo một khóa có quyền đó, hoặc hỏi một trong những người trong helpers. Một khóa không bao giờ có nhiều quyền hơn thành viên đã tạo ra nó (xem xác thực và khóa API).

Yêu cầu không hợp lệ

Một tham số hoặc trường trong body vi phạm schema sẽ nhận 422, với mỗi vấn đề một mục trong errors. Yêu cầu sai định dạng, chẳng hạn JSON không phân tích được, nhận 400 với cùng mã.

422 Unprocessable Entity

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [{ "message": "expected number <= 100", "location": "query.pageSize", "value": 500 }],
  "code": "validation_failed"
}

Với những kiểm tra do ReputeCast tự thực hiện, câu thông báo nằm trong detail và trường bị lỗi nằm trong errors, ví dụ "detail": "Use a work email." với "location": "body.email".

Vượt giới hạn tốc độ

Khi vượt tốc độ yêu cầu cho phép của mỗi khóa, API trả về 429 kèm header Retry-After:

429 Too Many Requests

{
  "code": "rate_limited",
  "detail": "Rate limit reached. Requests resume within a minute; batch endpoints accept up to 1,000 items per call.",
  "status": 429,
  "title": "Too Many Requests"
}

Con số “1,000 items” trong thông báo này đúng với thao tác thêm vào danh sách chặn gửi; thao tác gửi giao dịch theo lô nhận tối đa 100 thư. Hãy chờ số giây ghi trong Retry-After rồi gửi lại. Giới hạn tốc độ API liệt kê mọi giới hạn.

Ngôn ngữ của detail

Các câu do ReputeCast viết trong detail (chẳng hạn thiếu quyền, lỗi đăng nhập, không tìm thấy đối tượng và các bước kiểm tra dữ liệu của chính ReputeCast) dùng ngôn ngữ của yêu cầu nếu ReputeCast có ngôn ngữ đó (en hoặc vi): ngôn ngữ mà header Accept-Language yêu cầu, nếu không thì ngôn ngữ ứng dụng của thành viên đang đăng nhập, nếu không nữa thì tiếng Anh. Khóa API nhận tiếng Anh trừ khi bạn gửi header này. Phần do framework viết vẫn là tiếng Anh, như validation failed và các message trong errors như expected number <= 100. Với Accept-Language: vi, detail khi không tìm thấy chiến dịch là Không tìm thấy chiến dịch., còn detail của lỗi thiếu quyền sẽ như sau:

403 Forbidden, Accept-Language: vi

{
  "title": "Forbidden",
  "status": 403,
  "detail": "Để quản lý khóa API, bạn cần quyền apikeys:manage. Hãy hỏi Marcus Chen hoặc Linh Nguyen.",
  "code": "permission_denied",
  "permission": "apikeys:manage",
  "helpers": ["Marcus Chen", "Linh Nguyen"]
}

code, permission và các trường khác không bao giờ thay đổi theo ngôn ngữ.

Xử lý lỗi

• Rẽ nhánh theo status và code. Coi detail là văn bản dành cho người đọc.
• 401: khóa bị thiếu, không tồn tại, đã bị thu hồi hoặc đã hết hạn. Hãy sửa khóa; thử lại không giúp được gì.
• 403: thiếu một quyền (permission_denied), thao tác cần một người đã đăng nhập (humans_only), hoặc một khóa tích hợp đã gọi một thao tác mà tích hợp của nó không dùng (integration_operation_denied).
• 404, 409, 410, 422: hãy sửa yêu cầu. Các mã 409 như version_conflict và idempotency_key_reused cho biết điều gì đã thay đổi.
• 429: chờ theo Retry-After. Với lượt gửi giao dịch, hãy thử lại với cùng Idempotency-Key để mỗi thư chỉ được gửi một lần (xem gửi email giao dịch bằng API).
• 502 và 503: một dịch vụ bên ngoài hoặc một phần của máy chủ không phản hồi. Hãy thử lại với độ trễ tăng dần.

Mã lỗi

Các mã được nhóm theo khu vực. Ở một số thao tác, một mã có thể đi kèm trạng thái HTTP khác; bảng ghi trạng thái thường gặp.

Xác thực

Mã	Trạng thái HTTP	Ý nghĩa
unauthenticated	401	Không có phiên đăng nhập hoặc khóa API hợp lệ: bạn chưa đăng nhập, hoặc khóa không tồn tại, đã bị thu hồi hay đã hết hạn (với khóa hết hạn, trường detail ghi ngày hết hạn). Phản hồi 401 có header WWW-Authenticate: Bearer realm="reputecast".
session_expired	401	Phiên đăng nhập đã hết hạn hoặc đã kết thúc. Hãy đăng nhập lại; nội dung chưa lưu trong thẻ vẫn được giữ.

Quyền

Mã	Trạng thái HTTP	Ý nghĩa
permission_denied	403	Người gọi thiếu một quyền. Trường permission ghi khóa quyền còn thiếu và helpers liệt kê tối đa hai thành viên có quyền đó. Mã này cũng được trả về khi dùng khóa ở một không gian làm việc khác và khi gọi thao tác chỉ khóa tích hợp mới được gọi.
escalation_denied	403	Bạn không thể cấp quyền mà chính bạn không có, ví dụ cho một vai trò, khóa API hoặc tác tử. Khi chỉ thiếu một quyền, trường permission ghi khóa quyền đó.
humans_only	403	Chỉ người đã đăng nhập mới thực hiện được thao tác này, khóa API và tác tử MCP thì không.
forbidden	403	Lọc liên hệ theo trạng thái trả phí cần quyền earn:view.

Yêu cầu

Mã	Trạng thái HTTP	Ý nghĩa
workspace_not_found	404	Không gian làm việc trong đường dẫn không tồn tại, hoặc người gọi không phải thành viên của không gian làm việc đó.
not_found	404	Tài nguyên trong đường dẫn không tồn tại trong không gian làm việc này. Trường detail cho biết thứ bị thiếu, chẳng hạn "Không tìm thấy chiến dịch."
conflict	409	Yêu cầu xung đột với trạng thái hiện tại của tài nguyên. Trường detail cho biết cần thay đổi gì.
validation_failed	422	Nội dung hoặc tham số của yêu cầu không hợp lệ. errors[] liệt kê từng lỗi kèm vị trí, chẳng hạn body.email. Yêu cầu sai định dạng trả về 400 với cùng mã này.
rate_limited	429	Quá nhiều yêu cầu: vượt giới hạn tốc độ của IP hoặc khóa API, giới hạn riêng của khóa cho email giao dịch hoặc chuyển đổi, hoặc một lời nhắc được gửi lại trong vòng một giờ. Hãy chờ theo header Retry-After.
idempotency_key_reused	409	Cùng một Idempotency-Key được gửi kèm một yêu cầu khác: trong vòng 24 giờ với lần gửi email giao dịch, hoặc cho một chuyển đổi khác. Hãy dùng khóa mới cho yêu cầu mới.
slug_taken	409	Địa chỉ (slug) đang hoặc đã từng được một bài viết, thẻ, trang hoặc sản phẩm khác dùng. Hãy chọn địa chỉ khác.
version_conflict	409	Có người đã lưu một phiên bản mới hơn sau khi bạn mở (chiến dịch, tin nhắn, email, phiên bản ngôn ngữ, trang hoặc bản nháp giao dịch). Hãy tải lại để xem thay đổi của họ, rồi lưu lại.

Dịch vụ

Mã	Trạng thái HTTP	Ý nghĩa
provider_unavailable	502	Một nhà cung cấp gửi thư hoặc dịch vụ bên ngoài khác không chấp nhận thay đổi hoặc không kết nối được. Trường detail chứa phản hồi của nhà cung cấp; không có gì khác bị thay đổi. Một số thao tác trả về mã này với trạng thái 409 hoặc 503.
unavailable	503	Một phần của máy chủ hiện chưa phản hồi được, ví dụ bước kiểm tra chính sách đăng nhập. Hãy thử lại sau giây lát. Tính năng không có trong bản build này trả về 501.

Đăng nhập và tài khoản

Mã	Trạng thái HTTP	Ý nghĩa
password_change_required	403	Tài khoản vẫn đang dùng mật khẩu tạm thời. Hãy thay mật khẩu để tiếp tục.
two_factor_setup_required	403	Hệ thống yêu cầu xác thực hai lớp. Hãy thêm khóa truy cập hoặc ứng dụng xác thực để tiếp tục.
locked	429	Quá nhiều lần đăng nhập thất bại: tài khoản bị khóa đến thời điểm ghi trong trường detail. meta chứa lockedUntil và failures.
invalid_credentials	401	Email hoặc mật khẩu không đúng (trường detail cho biết còn bao nhiêu lần thử). Khi kết nối nhà cung cấp gửi thư, mã này đi kèm 422 nếu nhà cung cấp từ chối thông tin xác thực.
account_deactivated	403	Tài khoản đã bị vô hiệu hóa. Quản trị viên hệ thống có thể kích hoạt lại; không có gì bị xóa.
challenge_expired	401	Yêu cầu đăng nhập hoặc yêu cầu khóa truy cập đã hết hạn, hoặc đã nhập sai mã quá nhiều lần. Hãy bắt đầu lại. Với yêu cầu khóa truy cập, mã này đi kèm 400.
email_change_expired	410	Liên kết xác nhận đổi email đã hết hạn, đã được dùng hoặc thuộc tài khoản khác. Hãy đổi email lại từ Tài khoản và bảo mật.
identity_managed	409	Tên miền email bắt buộc dùng đăng nhập một lần (SSO), nên danh tính đăng nhập do tổ chức quản lý và không thể hủy liên kết.
invalid_code	401	Mã xác thực hai lớp không đúng. meta.attemptsLeft cho biết còn bao nhiêu lần thử.
invite_accepted	410	Lời mời đã được dùng. Hãy đăng nhập để tiếp tục.
invite_expired	410	Lời mời đã hết hạn. Hãy nhờ người đã mời bạn gửi lời mời mới.
invite_not_found	404	Liên kết mời không hợp lệ. Hãy kiểm tra bạn đã sao chép đủ liên kết, hoặc xin lời mời mới.
invite_revoked	410	Lời mời đã bị thu hồi, nên liên kết không còn dùng được.
invite_sign_in	409	Email được mời đã có tài khoản. Hãy đăng nhập để chấp nhận lời mời.
invite_wrong_account	409	Lời mời dành cho một email khác với tài khoản bạn đang đăng nhập. Hãy đăng xuất và tiếp tục, hoặc xin lời mời cho tài khoản này.
last_method	409	Đây là cách đăng nhập duy nhất của tài khoản. Hãy thêm khóa truy cập hoặc mật khẩu trước khi xóa hay hủy liên kết cách này.
last_second_factor	409	Tài khoản bắt buộc xác thực hai lớp, và đây là yếu tố thứ hai cuối cùng. Hãy thiết lập ứng dụng xác thực hoặc thêm khóa truy cập khác trước.
method_disabled	403	Cách đăng nhập này (mật khẩu hoặc khóa truy cập) đã tắt trên hệ thống. Hãy dùng cách khác, chẳng hạn đăng nhập một lần.
passkey_failed	401	Khóa truy cập không dùng được cho tài khoản này. Hãy thử lại, hoặc đăng nhập bằng email và mật khẩu.
passkey_rejected	422	Không xác minh được khóa truy cập. Hãy thử lại, hoặc dùng thiết bị hay khóa bảo mật khác.
public_url_invalid	409	Khóa truy cập cần URL công khai của hệ thống, với tên miền thay vì địa chỉ IP. Quản trị viên hệ thống đặt URL này trong Quản trị hệ thống.
reset_expired	410	Liên kết đặt lại mật khẩu đã quá 15 phút hoặc đã được dùng. Hãy yêu cầu liên kết mới; mật khẩu hiện tại vẫn dùng được.
setup_incomplete	409	Một bước thiết lập trước đó chưa xong: trước hết hãy thay mật khẩu tạm thời, thêm khóa truy cập hoặc ứng dụng xác thực và xác nhận thông tin cơ bản của hệ thống.
sso_required	403	Tên miền của email này dùng đăng nhập một lần (SSO), nên đăng nhập bằng mật khẩu và khóa truy cập đã tắt cho tên miền đó.

Quản trị hệ thống

Mã	Trạng thái HTTP	Ý nghĩa
agency_off	403	Chế độ agency đang tắt trên hệ thống này. Quản trị viên hệ thống bật chế độ này trong Quản trị hệ thống › Hệ thống và cập nhật.
last_admin	409	Người dùng này là quản trị viên hệ thống cuối cùng. Hãy đưa người khác thành quản trị viên hệ thống trước.
lockout_risk	409	Thay đổi chính sách đăng nhập này sẽ khiến bạn không còn cách nào để đăng nhập. Hãy thêm khóa truy cập hoặc liên kết một cách đăng nhập vẫn được bật, rồi lưu lại.
reauth_required	403	Hãy đăng nhập lại trước: với nhà cung cấp danh tính (IdP) trước khi chuyển quyền sở hữu (trong vòng 10 phút), hoặc bằng xác thực hai lớp trước khi đặt lại xác thực hai lớp của người khác.
restore_expired	410	Không gian làm việc đã bị xóa hơn 7 ngày trước và không thể khôi phục.

Đăng nhập một lần (SSO)

Mã	Trạng thái HTTP	Ý nghĩa
sso_incomplete	409	Kết nối SSO còn thiếu các cài đặt cần cho lần đăng nhập thử hoặc để bật kết nối. Trường detail liệt kê các cài đặt đó.
sso_unreachable	502	Không kết nối được nhà cung cấp danh tính (IdP) cho lần đăng nhập thử. Trường detail chứa lỗi.

Nhóm

Mã	Trạng thái HTTP	Ý nghĩa
last_owner	409	Thành viên này là Chủ sở hữu cuối cùng: một không gian làm việc luôn cần ít nhất một Chủ sở hữu, nên không thể đổi vai trò, xóa hay vô hiệu hóa thành viên này. Hãy chuyển quyền sở hữu trước.

Nhà cung cấp gửi thư và định tuyến

Mã	Trạng thái HTTP	Ý nghĩa
bulk_terms	409	Điều khoản của nhà cung cấp không cho phép thư hàng loạt hoặc thư tiếp thị trên tuyến này. Hãy chọn nhà cung cấp khác, hoặc giữ nhà cung cấp này và xác nhận đã biết điều khoản. meta.issues liệt kê các tuyến.
no_route	422	Công cụ thử tuyến không tìm thấy nhà cung cấp nào cho thư này: tuyến chưa có nhà cung cấp chính, hoặc trỏ đến một nhà cung cấp không còn được kết nối.

Chiến dịch và Độ sẵn sàng gửi

Mã	Trạng thái HTTP	Ý nghĩa
accessibility_unchecked	422	Không kiểm tra được khả năng tiếp cận của email vì MJML không biên dịch được. Các thay đổi vẫn được lưu.
readiness_blocked	409	Độ sẵn sàng gửi vẫn chặn lần gửi (chiến dịch, số của bản tổng hợp, tin nhắn, chiến dịch thông báo đẩy hoặc WhatsApp). Hãy sửa mọi mục kiểm tra đang chặn trước.
readiness_changed	409	Độ sẵn sàng gửi đã được kiểm tra lại sau khi bạn xem. Hãy xem kết quả mới và xác nhận lại.
readiness_incomplete	409	Một số mục kiểm tra không chạy được. Hãy chạy lại, hoặc tiếp tục chỉ với dữ liệu của nhà cung cấp.
readiness_running	409	Độ sẵn sàng gửi đang được kiểm tra. Hãy thử lại khi kiểm tra xong.
readiness_stale	409	Chiến dịch đã thay đổi sau khi kiểm tra. Hãy chạy lại kiểm tra trước khi gửi.
readiness_unavailable	503	Tiến trình máy chủ này không chạy Độ sẵn sàng gửi. Hãy thử lại trên một tiến trình có chạy kiểm tra này.
sending_unavailable	503	Bộ máy gửi thư không chạy trong bản cài đặt này, nên chưa có gì được lên lịch. Kết quả kiểm tra, lịch gửi và phê duyệt vẫn được giữ.

Phê duyệt

Mã	Trạng thái HTTP	Ý nghĩa
approval_invalidated	409	Phê duyệt không còn áp dụng cho chiến dịch vì đã có thay đổi sau khi được phê duyệt. Hãy gửi lại yêu cầu phê duyệt.
approval_not_required	409	Không có quy tắc phê duyệt nào khớp với lần gửi này, nên bạn có thể tự lên lịch.
approval_required	409	Lần gửi hoặc xuất bản này cần được phê duyệt trước. Trường detail ghi tên quy tắc; hãy gửi yêu cầu phê duyệt rồi thử lại. Mã này cũng được trả về khi xuất bản bài viết, trang đích hoặc mẫu giao dịch thuộc phạm vi của một quy tắc phê duyệt.
no_approvers	409	Lần gửi cần nhiều lượt phê duyệt từ người khác hơn số người phê duyệt mà không gian làm việc có. Chủ sở hữu có thể cấp campaigns:approve cho một vai trò khác.
no_client_approver	409	Lần gửi cần phê duyệt của khách hàng, nhưng chưa ai trong không gian làm việc của khách hàng có vai trò Người duyệt phía khách hàng. Hãy mời người duyệt của khách hàng trong Cài đặt › Nhóm.
restore_incomplete	409	Chiến dịch vẫn khác phiên bản đã được phê duyệt. Hãy gửi lại yêu cầu phê duyệt.

Người đăng ký

Mã	Trạng thái HTTP	Ý nghĩa
no_system_provider	409	Chưa có nhà cung cấp gửi thư nào được kết nối với luồng Hệ thống, nên chưa gửi được email xác nhận đăng ký. Hãy kết nối một nhà cung cấp trong Nhà cung cấp gửi thư.

Nhập dữ liệu

Mã	Trạng thái HTTP	Ý nghĩa
file_columns	422	Một số dòng của tệp không khớp với các cột. Trường detail liệt kê các dòng đó; hãy sửa tệp hoặc bỏ qua những dòng này.
file_unreadable	422	Không đọc được tệp CSV hoặc XLSX đã tải lên. Trường detail cho biết lý do.
source_auth_failed	422	Nền tảng nguồn mà bạn nhập dữ liệu (liên hệ hoặc mẫu giao dịch) đã từ chối khóa API hoặc thông tin xác thực. meta.sourceStatus chứa mã trạng thái HTTP của nền tảng đó.
source_bad_response	502	Nền tảng nguồn mà bạn nhập dữ liệu trả về nội dung ReputeCast không đọc được. Trường detail chứa nội dung đã trả về.
source_not_found	422	Nền tảng mẫu giao dịch không có mẫu hoặc phiên bản này, hoặc tài khoản không có gì để nhập.
source_rate_limited	429	Nền tảng nguồn mà bạn nhập dữ liệu đang giới hạn yêu cầu. Quá trình nhập chậm lại; hãy thử lại sau. meta.sourceStatus chứa mã trạng thái HTTP của nền tảng đó.
source_unavailable	502	Nền tảng nguồn mà bạn nhập dữ liệu không phản hồi. Hãy thử lại sau vài phút.

Phân khúc

Mã	Trạng thái HTTP	Ý nghĩa
count_timeout	504	Việc đếm phân khúc mất hơn 10 giây. Phân khúc vẫn hoạt động khi gửi.
sql_disabled	409	Phân khúc SQL đang tắt trên cơ sở dữ liệu này. Hãy tạo role reputecast_segments và cấp role đó cho người dùng của ứng dụng, rồi chạy reputecast migrate up.
sql_error	422	Truy vấn của phân khúc SQL không hợp lệ. Trường detail chứa thông báo của cơ sở dữ liệu và, nếu biết, vị trí của lỗi.

Xác minh địa chỉ

Mã	Trạng thái HTTP	Ý nghĩa
no_verification_service	409	Chưa kết nối dịch vụ xác minh địa chỉ nào. Hãy kết nối một dịch vụ trong Cài đặt › Tích hợp.
nothing_to_check	409	Không có gì để xác minh: mọi địa chỉ đã chọn đều đã được kiểm tra trong 90 ngày qua, hoặc chưa chọn địa chỉ nào.

Tự động hóa

Mã	Trạng thái HTTP	Ý nghĩa
accessibility_blocked	409	Chính sách khả năng tiếp cận của không gian làm việc đang đặt là Chặn và một email trong quy trình có lỗi khả năng tiếp cận nghiêm trọng. Trường detail ghi tên email; hãy sửa email đó rồi xuất bản.

API email giao dịch

Mã	Trạng thái HTTP	Ý nghĩa
template_not_found	422	ID mẫu không tồn tại trong không gian làm việc này. Hãy kiểm tra ID trong trang Mẫu.
template_not_published	422	Mẫu có bản nháp nhưng chưa có phiên bản đang chạy. Hãy xuất bản mẫu trước.
missing_variables	422	Thiếu một biến bắt buộc trong data. Phản hồi liệt kê các biến bị thiếu.
invalid_recipient	422	Địa chỉ không phải là địa chỉ email hợp lệ. Hãy kiểm tra địa chỉ ngay trong ứng dụng của bạn.
recipient_suppressed	422	Thư gửi đến địa chỉ này đã bị trả lại, người nhận đã khiếu nại, hoặc địa chỉ là bẫy spam. Phản hồi cho biết lý do và ngày.
sender_not_verified	422	Địa chỉ from chưa phải người gửi Giao dịch đã xác minh. Hãy xác minh địa chỉ này trong Cài đặt › Người gửi.
attachments_too_large	422	Thư, tính cả tệp đính kèm, vượt giới hạn kích thước của tuyến: giới hạn nhỏ nhất trong các nhà cung cấp gửi thư của tuyến.
no_healthy_route	503	Mọi nhà cung cấp gửi thư trong tuyến đều đang gián đoạn. Hãy thử lại với cùng Idempotency-Key.
template_not_allowed	403	Khóa này không được gửi mẫu hoặc danh mục này. Hãy dùng khóa được phép, hoặc mở rộng phạm vi của khóa.
agents_never_send	403	Tác tử MCP không bao giờ gửi email giao dịch. Hãy gửi từ ứng dụng của bạn bằng khóa chỉ gửi.
content_removed	410	Nội dung đã kết xuất của thư không còn được lưu (theo thời hạn lưu nội dung), hoặc thư chưa từng được kết xuất. Phần tóm tắt và sự kiện vẫn được giữ đến hết thời hạn lưu siêu dữ liệu.
resend_unavailable	409	Không thể gửi lại thư này từ ReputeCast: biến nhạy cảm hoặc tệp đính kèm không được lưu, hoặc thư đến qua SMTP. Hãy gửi lại từ ứng dụng của bạn.

Mẫu giao dịch

Mã	Trạng thái HTTP	Ý nghĩa
breaking_change	409	Bản nháp thay đổi biến theo cách sẽ làm hỏng các lệnh gọi trong 7 ngày qua. Hãy chuyển biến thành không bắt buộc với giá trị mặc định, cập nhật ứng dụng của bạn trước, hoặc vẫn xuất bản. meta.breaking liệt kê các thay đổi.
template_does_not_render	422	Mẫu không kết xuất được với dữ liệu đã cho, hoặc bản nháp chưa xuất bản được. Trường detail cho biết lỗi ở đâu. Khi xuất bản và khi gửi yêu cầu phê duyệt, mã này đi kèm 409.

Khóa tích hợp

Mã	Trạng thái HTTP	Ý nghĩa
key_revoked	401	Khóa của tích hợp đã bị thu hồi. Hãy kết nối lại tích hợp trong Cài đặt › Tích hợp để nhận khóa mới.
key_expired	401	Khóa của tích hợp đã hết hạn. Hãy kết nối lại tích hợp trong Cài đặt › Tích hợp để nhận khóa mới.
owner_deactivated	403	Thành viên sở hữu khóa của tích hợp đã rời không gian làm việc, nên khóa mất các quyền. Người có quyền integrations:manage có thể tiếp quản khóa trong Cài đặt › Tích hợp; khóa vẫn giữ nguyên.
integration_operation_denied	403	Khóa này thuộc một tích hợp và chỉ dùng được cho các trình kích hoạt và hành động đang bật của tích hợp đó. Hãy thay đổi những gì khóa được phép làm trong Cài đặt › Tích hợp.
instance_unreachable	409	Tích hợp không truy cập được URL công khai của hệ thống. Hãy cấp cho hệ thống một địa chỉ công khai, hoặc chạy công cụ đó trong mạng của bạn.
managed_by_integration	409	Khóa API hoặc endpoint webhook này thuộc một tích hợp (Zapier, Make, n8n, WordPress). Hãy thay đổi trong Cài đặt › Tích hợp hoặc trong workflow.

Hành động tích hợp

Mã	Trạng thái HTTP	Ý nghĩa
unsubscribed	409	Liên hệ đã rời danh sách, và ReputeCast không thêm lại một người vào danh sách mà họ đã rời.
suppressed	409	Địa chỉ nằm trong danh sách chặn gửi, và ReputeCast không thêm địa chỉ bị chặn gửi. Trường detail cho biết ngày và lý do.
private_address	422	Địa chỉ webhook trỏ đến một mạng riêng. Địa chỉ này bị chặn cho đến khi quản trị viên hệ thống cho phép địa chỉ riêng (webhooks.allow_private_networks).

Trang web

Mã	Trạng thái HTTP	Ý nghĩa
certificate_failing	409	Chứng chỉ của tên miền tùy chỉnh đang lỗi, nên trang web chưa thể chạy trên tên miền đó. Hãy sửa trong Thương hiệu và tên miền trước.
featured_full	409	Trang chủ làm nổi bật tối đa 3 bài viết. Hãy bỏ nổi bật một bài trong Trang chủ và điều hướng trước.
header_full	409	Đầu trang web chứa tối đa 6 liên kết. Hãy xóa một liên kết trước.

Trang đích

Mã	Trạng thái HTTP	Ý nghĩa
nothing_to_publish	409	Không có thay đổi nào so với phiên bản đang chạy, nên không có gì để xuất bản.
reminders_exist	409	Tự động hóa gửi lời nhắc cho trang này đã tồn tại.

Trang đích và sản phẩm

Mã	Trạng thái HTTP	Ý nghĩa
checks_failed	409	Một mục kiểm tra trước khi xuất bản vẫn chặn trang hoặc sản phẩm. Danh sách kiểm tra cho biết còn thiếu gì.

Sản phẩm số

Mã	Trạng thái HTTP	Ý nghĩa
file_mismatch	422	Phần mở rộng của tệp không khớp với nội dung, nên người mua sẽ nhận được tệp mà máy tính của họ không mở được. Hãy tải lên đúng tệp, hoặc đổi tên tệp.
file_program	422	Tệp này là một chương trình. Không thể bán hoặc tặng chương trình dưới dạng tệp tải xuống.
price_change	409	Việc xuất bản sẽ thay đổi giá. Hãy xác nhận: người mua hiện tại vẫn giữ quyền truy cập và không ai bị tính phí lại.
stripe_key_rejected	409	Stripe đã từ chối khóa. Hãy thay khóa trong Kiếm tiền › Cài đặt › Thanh toán, rồi xuất bản lại.
stripe_not_connected	409	Stripe chưa được kết nối. Hãy kết nối Stripe trong Kiếm tiền › Cài đặt › Thanh toán trước: không có Stripe thì không ai mua được gì và không trao được phần thưởng phiếu giảm giá Stripe.
stripe_permission	409	Khóa Stripe không tạo được sản phẩm và giá. Hãy cấp các quyền đó cho khóa trong Stripe, rồi xuất bản lại.
stripe_unavailable	503	Stripe không phản hồi, nên chưa có gì được xuất bản hoặc chưa có phiên thanh toán nào bắt đầu, và không có khoản thanh toán nào bị thu. Hãy thử lại sau một phút.
upload_gone	404	Quá trình tải lên đã dừng và không có gì được giữ lại. Hãy chọn lại tệp.
upload_incomplete	409	Tệp chưa tải lên xong: mới nhận được một phần của tệp.
upload_offset	409	Một phần của tệp tải lên được nhận hai lần. Quá trình tải lên tiếp tục từ vị trí (offset) ghi trong trường detail.

Kiếm tiền và Stripe

Mã	Trạng thái HTTP	Ý nghĩa
already_complimentary	409	Liên hệ đã có quyền truy cập miễn phí. Hãy thay đổi quyền truy cập hiện có thay vì cấp mới.
import_not_matched	409	Hãy khớp các dòng nhập với Stripe trước.
import_started	409	Lần nhập hội viên trả phí này đã bắt đầu.
key_format	422	Giá trị này có vẻ không phải khóa Stripe. Khóa hạn chế bắt đầu bằng rk_live_ hoặc rk_test_.
key_rejected	422	Stripe báo khóa không hợp lệ: có thể khóa đã bị xoay vòng, bị xóa hoặc chỉ được sao chép một phần.
missing_permissions	422	Khóa Stripe thiếu các quyền ReputeCast cần. Hãy sửa khóa trong Stripe rồi thử lại.
mode_connected	409	Đã có một khóa chính thức hoặc thử nghiệm được kết nối. Hãy thay khóa đó trong Kiếm tiền › Cài đặt › Thanh toán.
no_email_column	422	Không tìm thấy cột email trong tệp hội viên trả phí. Hãy chọn cột chứa địa chỉ email.
not_cancelable	409	Không thể hủy thuê bao này ở đây: thuê bao đã kết thúc, hoặc không được thanh toán qua Stripe.
not_connected	409	Stripe chưa được kết nối, nên không thể nhập hội viên trả phí hoặc hủy thuê bao từ ReputeCast.
other_account	422	Khóa thuộc một tài khoản Stripe khác với tài khoản đã kết nối. Hãy dùng khóa của tài khoản đó, hoặc ngắt kết nối trước.
provider_not_available	422	Nhà cung cấp thanh toán này chưa khả dụng. Stripe là nhà cung cấp được hỗ trợ.
public_url_unreachable	409	Stripe không truy cập được URL công khai của hệ thống để đăng ký webhook. Hãy đặt REPUTECAST_PUBLIC_URL thành một địa chỉ trên internet, hoặc thêm webhook thủ công.
secret_key	422	Khóa bí mật của Stripe bị từ chối vì cho phép truy cập toàn bộ tài khoản Stripe. Hãy tạo khóa hạn chế để thay thế; chưa có gì được gửi đến Stripe hoặc được lưu lại.
tier_has_members	409	Đang có hội viên dùng gói này, nên không thể xóa gói. Hãy lưu trữ gói thay vì xóa: họ vẫn giữ quyền truy cập, và không ai có thể mua mới.
unmapped_price	422	Một giá Stripe trong lần nhập chưa được gán cho gói nào. Hãy gán giá đó cho một gói, hoặc giữ làm giá cũ.
unsettled_conflict	422	Một dòng khớp với nhiều khách hàng Stripe. Hãy chọn khách hàng Stripe mà người đó dùng để thanh toán, hoặc bỏ qua dòng này.
webhook_first	409	Hãy thiết lập webhook Stripe trước. Không có webhook, trạng thái trả phí không thể đồng bộ với Stripe.

Chuyển đổi

Mã	Trạng thái HTTP	Ý nghĩa
invalid_currency	422	Hãy gửi mã tiền tệ ISO 4217, chẳng hạn USD, EUR hoặc GBP.
invalid_value	422	Hãy gửi giá trị dưới dạng chuỗi số thập phân, chẳng hạn "29.00", với số chữ số thập phân không vượt quá mức mà loại tiền tệ cho phép.
missing_identity	422	Chuyển đổi không chỉ ra người nào: hãy gửi email của người đọc, token lượt nhấp (rc_click), hoặc cả hai.
occurred_at_out_of_range	422	occurred_at phải nằm trong 30 ngày qua và không ở tương lai.

Giới thiệu

Mã	Trạng thái HTTP	Ý nghĩa
checks_failing	409	Hãy sửa các mục kiểm tra chưa đạt để bật chương trình giới thiệu.
last_milestone	409	Chương trình cần ít nhất một mốc thưởng khi đang bật. Hãy thêm mốc khác trước, hoặc tắt chương trình.
link_active	409	Liên kết của người giới thiệu đang hoạt động.
link_paused	409	Liên kết của người giới thiệu đã tạm dừng.
list_fixed	409	Không thể đổi danh sách của chương trình sau khi chương trình đã từng bật.
not_codes	409	Phần thưởng của mốc này không phải là mã từ danh sách.
not_held	409	Một số lượt giới thiệu không còn bị tạm giữ để duyệt. Hãy tải lại hàng chờ.
program_exists	409	Danh sách đã có chương trình giới thiệu. Mỗi danh sách chỉ có một chương trình.
program_on	409	Hãy tắt chương trình giới thiệu trước khi xóa.
stale_settings	409	Có người đã lưu cài đặt chương trình sau khi bạn mở. Hãy tải lại để xem thay đổi của họ, rồi lưu thay đổi của bạn.
undo_late	409	Không thể hoàn tác nữa: quyết định đã được đưa ra hơn 10 giây trước, hoặc đã có phần thưởng được gửi.

Đề xuất và đối tác

Mã	Trạng thái HTTP	Ý nghĩa
code_expired	422	Mã đối tác đã hết hạn. Mã đối tác có hiệu lực trong 7 ngày; hãy xin bản tin đó một mã mới.
code_revoked	422	Bản tin đó đã thu hồi mã đối tác. Hãy xin họ một mã mới.
code_unknown	422	Hệ thống đối tác không nhận ra mã này. Hãy kiểm tra xem bạn đã sao chép đủ chưa.
code_used	422	Mã đối tác đã được dùng. Mỗi mã chỉ kết nối được một lần; hãy xin một mã mới.
link_ended	409	Quan hệ đối tác đã kết thúc. Để kết nối lại, cần một mã đối tác mới.
link_invalid	409	Liên kết đối tác không còn hợp lệ, nên không thể tạm dừng, tiếp tục hoặc cấp khóa bí mật mới. Để kết nối lại, cần một mã đối tác mới.
no_public_url	409	Liên kết đối tác cần URL công khai của hệ thống. Quản trị viên hệ thống đặt URL này.
not_a_code	422	Giá trị này không phải là mã đối tác (có thể là liên kết đến trang đăng ký). Mã đối tác có dạng https://reputecast.example/p/XXXX-XXXX-XXXX.
not_recommending_you	409	Chỉ những đối tác đề xuất bạn mới có giới hạn mỗi ngày do bạn đặt.
partner_link	409	Một đề xuất đối tác được tạm dừng cùng liên kết đối tác của nó, việc này cần quyền grow:connect.
partner_private	422	Địa chỉ đối tác là địa chỉ riêng. Hệ thống đối tác phải phản hồi tại một địa chỉ HTTPS công khai.
partner_unreachable	422	Hệ thống đối tác không phản hồi qua HTTPS. Hãy kiểm tra lại địa chỉ, hoặc thử lại sau vài phút. Với liên kết đã có, mã này đi kèm 502.
partner_unsupported	422	Hệ thống đối tác đang chạy phiên bản ReputeCast chưa có liên kết đối tác. Hãy đề nghị họ cập nhật, hoặc đề xuất trang đăng ký của họ dưới dạng liên kết.
paused_by_partner	409	Đối tác đã tạm dừng liên kết này. Chỉ họ mới có thể tiếp tục.

Thông báo đẩy trên web

Mã	Trạng thái HTTP	Ý nghĩa
not_a_push_site	409	Trang web của lời nhắc đăng ký chưa phải là trang web nhận thông báo đẩy. Hãy thêm trang đó trong Thông báo đẩy › Thiết lập; người đọc chưa đăng ký được cho đến khi trang được thêm.
push_off	409	Hãy bật thông báo đẩy trong Nhà cung cấp gửi thư › Thông báo đẩy trước: lời nhắc đăng ký dùng khóa của không gian làm việc để đăng ký cho người đọc.

Thông báo đẩy trên web và WhatsApp

Mã	Trạng thái HTTP	Ý nghĩa
stale_version	409	Chiến dịch đã thay đổi sau khi bạn mở hoặc kiểm tra. Hãy tải lại hoặc kiểm tra lại.

SMS

Mã	Trạng thái HTTP	Ý nghĩa
credentials_rejected	422	Nhà cung cấp SMS đã từ chối thông tin xác thực. Hãy kiểm tra lại rồi thử lại.
no_sender	409	Chưa có người gửi nào nhắn tin được đến quốc gia của số này. Hãy thêm tuyến cho quốc gia đó trong Định tuyến và quy tắc.
opted_out_by_text	409	Số này đã hủy nhận bằng tin nhắn. Chỉ chính người đó mới đăng ký nhận lại được, bằng cách nhắn START.
provider_unreachable	502	Nhà cung cấp SMS không phản hồi. Hãy thử lại sau một phút.
review_changed	409	Nội dung tin nhắn, người nhận, tuyến hoặc chi phí đã thay đổi sau khi bạn kiểm tra. Hãy xem lại và xác nhận.

WhatsApp

Mã	Trạng thái HTTP	Ý nghĩa
meta_error	502	Meta trả về lỗi. Trường detail chứa thông báo của Meta.
meta_unavailable	502	Graph API của Meta không phản hồi. Hãy thử lại sau giây lát.
token_rejected	502	Meta đã từ chối access token. Hãy thay token để đồng bộ mẫu.
window_closed	409	Khung chăm sóc khách hàng 24 giờ đã đóng, nên không gửi được tin trả lời tự do. Hãy gửi một mẫu đã được duyệt.

Trợ lý AI

Mã	Trạng thái HTTP	Ý nghĩa
ai_cap_reached	409	Đã dùng hết giới hạn token AI hoặc ngân sách của tháng này. Tính năng AI hoạt động lại vào ngày ghi trong trường detail, hoặc người có quyền integrations:manage có thể nâng giới hạn.
ai_demo_model	409	Mô hình mẫu của bản demo chỉ trả lời trong môi trường phát triển và chỉ dịch sang tiếng Tây Ban Nha và tiếng Đức. Hãy kết nối mô hình của riêng bạn.
ai_feature_off	409	Tính năng AI này đang tắt cho không gian làm việc. Người có quyền integrations:manage có thể bật trong Cài đặt › Tích hợp · Trợ lý AI.
ai_key_rejected	409	Nhà cung cấp mô hình đã từ chối khóa của không gian làm việc, nên chưa có gì được gửi đi. Người có quyền integrations:manage có thể thay khóa. Nếu khóa bị từ chối trong lúc gọi, mã này đi kèm 502.
ai_no_image_input	409	Văn bản thay thế cần mô hình đọc được hình ảnh, mà mô hình đã kết nối thì không đọc được.
ai_not_configured	409	Chưa có mô hình AI nào được kết nối với không gian làm việc. Hãy kết nối một mô hình trong Cài đặt › Tích hợp · Trợ lý AI.
ai_not_sent	409	Chiến dịch chưa gửi gì, nên chưa có kết quả để tóm tắt.
ai_one_model	409	Mỗi không gian làm việc có một mô hình AI. Để đổi, hãy ngắt kết nối nhà cung cấp hiện tại trước.
ai_private_address	422	Địa chỉ của mô hình là địa chỉ riêng và hệ thống không cho phép địa chỉ riêng. Quản trị viên hệ thống có thể cho phép. Nếu phát hiện trong lúc gọi, mã này đi kèm 502.
ai_provider_error	502	Không đọc được phản hồi của nhà cung cấp mô hình hoặc nhà cung cấp gặp lỗi, nên không có gì bị thay đổi. Khi hết thời gian chờ, mã này đi kèm 504.
ai_rate_limited	503	Nhà cung cấp mô hình đang giới hạn yêu cầu từ không gian làm việc. Hãy thử lại sau thời điểm ghi trong trường detail; không có gì bị thay đổi.
ai_source_changed	409	Email đã thay đổi sau khi bản dịch được tạo. Hãy dịch lại.
ai_suggestion_gone	409	Gợi ý không phải của bạn hoặc đã quá một ngày. Hãy yêu cầu gợi ý mới.
ai_test_failed	422	Lệnh gọi thử đến mô hình thất bại, nên cài đặt chưa được lưu. meta.test chứa kết quả.

HostRepute và khả năng vào hộp thư

Mã	Trạng thái HTTP	Ý nghĩa
hostrepute_error	502	HostRepute trả về lỗi. Chưa có gì được lưu.
hostrepute_reconnect	409	HostRepute đã từ chối token. Hãy kết nối lại HostRepute rồi thử lại.
hostrepute_required	409	Yêu cầu gỡ khỏi danh sách được gửi qua HostRepute, mà HostRepute chưa được kết nối. Hãy yêu cầu gỡ khỏi danh sách trên trang riêng của danh sách chặn đó (meta.delistUrl).
hostrepute_scope	409	Kết nối HostRepute thiếu phạm vi assets:write, nên không thêm được tài sản vào giám sát. Hãy kết nối lại HostRepute và chấp thuận phạm vi này.
hostrepute_unavailable	503	Không kết nối được HostRepute. Chưa có gì được lưu.
monitor_limit_reached	409	Gói của nhóm HostRepute không giám sát thêm tài sản được nữa. Đây là giới hạn của HostRepute, không phải của ReputeCast.

Kiểm tra vị trí thư

Mã	Trạng thái HTTP	Ý nghĩa
oauth_not_set_up	409	Ứng dụng đăng nhập của nhà cung cấp chưa được thiết lập cho hộp thư thử. Quản trị viên hệ thống thêm client ID và client secret của ứng dụng đó trong Quản trị hệ thống › Xác thực.
placement_copies_gone	409	Các bản sao đã bị xóa khỏi hộp thư thử.
placement_not_ready	409	Chưa thể bắt đầu kiểm tra vị trí thư. Trường detail và meta.problems cho biết còn thiếu gì.
placement_not_waiting	409	Lần kiểm tra không còn chờ bản sao nữa.

Bản tin định kỳ

Mã	Trạng thái HTTP	Ý nghĩa
digest_feed_unread	409	Nguồn cấp của bản tổng hợp chưa được đọc. Hãy đọc nguồn cấp một lần trước khi bật bản tổng hợp.
digest_needs_audience	409	Hãy chọn người nhận trước khi bật bản tổng hợp.
tests_unavailable	503	Tiến trình máy chủ này không gửi thử được.

Thăm dò và khảo sát

Mã	Trạng thái HTTP	Ý nghĩa
survey_incomplete	422	Mọi câu hỏi của khảo sát phải hoàn chỉnh trước khi xuất bản. Trường detail liệt kê những gì còn thiếu.

Cửa hàng

Mã	Trạng thái HTTP	Ý nghĩa
store_not_connected	409	Không có cửa hàng WooCommerce nào được kết nối ứng với địa chỉ mà plugin gửi lệnh gọi. Hãy kết nối cửa hàng trong Cài đặt › Tích hợp trước.
store_rate_limited	429	Shopify hoặc WooCommerce đang giới hạn yêu cầu. Quá trình đồng bộ chậm lại và tự tiếp tục.
store_unavailable	503	Shopify hoặc WooCommerce không phản hồi. Hãy thử lại sau vài phút.