Lỗi

Trang này dành cho người viết tích hợp: nó tra code mà API trả về. Nếu bạn chỉ muốn biết vì sao một bài không đăng được và phải làm gì, hãy đọc Vì sao bài không đăng được, nơi xếp các câu báo lỗi thật theo nguyên nhân.

Mọi request thất bại đều trả về cùng một cấu trúc JSON, bất kể endpoint nào hay lỗi gì:

{
  "error": {
    "code": "invalid_request",
    "message": "`platforms` is required (array or comma-separated)."
  }
}

code là một chuỗi ổn định, có thể đọc bằng máy, bạn có thể dùng nó để rẽ nhánh xử lý. message là mô tả dễ đọc cho người, hữu ích khi ghi log, nhưng đừng parse nó vì nội dung có thể thay đổi theo thời gian. Khi nền tảng đích từ chối một bài đăng, message mở đầu bằng nguyên văn của nền tảng đó, thường là tiếng Anh. Nếu MADIAD Hub có bản dịch tiếng Việt cho câu đó, bản dịch nằm ngay sau · Tạm dịch:. Đây là bản dịch đúng nghĩa: nó giữ đủ các mệnh đề và các con số của nền tảng, không thêm lời khuyên nào của chúng tôi. Câu nào chưa có bản dịch thì giữ nguyên tiếng Anh chứ không đoán bừa. Phần duy nhất bị sửa còn lại là những gì thuộc về chúng tôi: địa chỉ hỗ trợ và link tài liệu đều trỏ về MADIAD, còn định danh Profile nội bộ thì được gỡ bỏ.

Bảng mã lỗi

`code`	HTTP status	Xảy ra khi nào	Cách xử lý
`unauthorized`	401	API key thiếu, sai định dạng hoặc không hợp lệ (hoặc session dashboard đã hết hạn trên các route dùng browser session).	Kiểm tra header `Authorization: Bearer`. Cấp lại hoặc xoay vòng key từ dashboard. Không nên retry khi chưa sửa thông tin xác thực.
`forbidden`	403	Tài khoản hợp lệ nhưng không được phép thực hiện hành động này, ví dụ tài khoản đang ở trạng thái `expired` hoặc `banned`, hoặc một tính năng không nằm trong gói hiện tại. Với bình luận, mọi gói trả phí đều ghi được, nên `403` ở đó gần như luôn là tài khoản chưa kích hoạt hoặc đã hết hạn, không phải chuyện gói. Với nhắn tin, AutoDM và trả lời đánh giá Google thì đó đúng là chuyện gói.	Không retry nguyên trạng. Đọc `GET /v1/usage` để biết gói hiện tại có gì, rồi kiểm tra trạng thái tài khoản hoặc nâng cấp gói.
`not_found`	404	Route không tồn tại, hoặc một resource được tham chiếu (Profile…) không thuộc về tài khoản của bạn.	Kiểm tra lại URL và các ID. Không retry được nếu không đổi request.
`invalid_request`	400	Request không hợp lệ, có thể do phía Hub hoặc do chính nền tảng đích từ chối: thiếu field bắt buộc, caption hoặc title vượt giới hạn ký tự của nền tảng, liệt kê nền tảng không hỗ trợ, URL không phải link `https://` hợp lệ, nền tảng từ chối nội dung.	Sửa request theo `message`. Không retry được nếu không đổi payload.
`quota_exceeded`	429	Một hạn mức đã dùng hết: hạn mức lượt xử lý video hằng tháng hoặc số DM theo ngày. Đăng bài không còn hạn mức tháng trên gói trả phí, nên với một lệnh đăng thì lỗi này chỉ có nghĩa là tài khoản chưa có gói đang hoạt động. Tính năng chưa bao giờ được bật thì trả `403 forbidden`, và cái đó đợi bao lâu cũng không hết.	Không retry được cho tới khi hạn mức reset hoặc gói được kích hoạt/nâng cấp. Kiểm tra Mức sử dụng và hiển thị thông báo cho người dùng thay vì lặp lại retry.
`no_active_plan`	403	Bạn đang cố kết nối một tài khoản mạng xã hội (tạo connect link) nhưng tài khoản chưa có gói đang hoạt động (hạn mức Profile bằng 0).	Kích hoạt gói dịch vụ từ trang thanh toán của dashboard trước. Không retry nguyên trạng.
`profile_limit_reached`	403	Tạo thêm Profile mới sẽ vượt giới hạn Profile của gói hiện tại.	Nâng cấp gói hoặc xoá bớt một Profile không dùng đến, rồi thử lại.
`rate_limited`	429	Bạn đã vượt giới hạn số request mỗi phút (tách biệt với các hạn mức sử dụng, xem Rate limit), hoặc nền tảng đích chặn tốc độ lời gọi.	Giảm tốc độ gửi và tuân theo header `Retry-After` (tính bằng giây) trước khi thử lại.
`idempotency_conflict`	409	`Idempotency-Key` bạn gửi đã được dùng cho một request với tham số khác.	Dùng key mới cho request thực sự mới, hoặc kiểm tra lại payload có khớp với lần gửi đầu tiên không. Không nên retry an toàn với cùng key nhưng khác body.
`idempotency_in_progress`	409	Một request với `Idempotency-Key` này vẫn đang được xử lý (một lần retry đồng thời hoặc chồng lấn xảy ra khi lần thử đầu chưa xong).	Đợi một chút rồi thử lại cùng request với cùng key, nó sẽ nhận kết quả đã lưu ngay khi lần thử đầu hoàn tất.
`page_pin_conflict`	409	Request có nêu một trang hoặc địa điểm (`facebook_page_id`, `target_linkedin_page_id` hoặc `gbp_location_id`) nhưng Profile đang ghim một trang khác. Trang được ghim đè lên trang gửi kèm mỗi lần đăng, nên nếu vẫn đăng thì bài sẽ lên trang đã ghim mà vẫn báo thành công.	Bỏ trường đó đi để đăng vào trang đã ghim, hoặc gỡ ghim trước, xem Ghim Trang vào Profile. Gửi lại y nguyên thì không thể thành công.
`page_pin_unverified`	503	Request có nêu một trang, nhưng không kiểm tra được Profile đang ghim trang nào. Ghim sẽ đè lên trường đó, nên nếu cứ đăng thì có nguy cơ bài lên nhầm trang.	Thử lại sau một lát, đây là lỗi tạm thời. Hoặc bỏ trường đó đi để đăng vào trang mà profile đang ghim.
`platform_not_startable`	400	Nền tảng có hỗ trợ đăng bài nhưng không khởi tạo được từ endpoint kết nối theo từng nền tảng (Bluesky dùng app password chứ không phải OAuth).	Nền tảng này hiện chưa hỗ trợ tự kết nối. Liên hệ hỗ trợ nếu bạn cần dùng.
`link_not_found`	404	Token của liên kết kết nối không tồn tại hoặc đã hết hạn (liên kết sống 48 giờ). Một mã dùng chung cho cả hai trường hợp, để không ai dò được token nào có thật.	Tạo liên kết mới bằng `POST /v1/connections/start`.
`platform_not_connected`	409	Profile chưa kết nối tài khoản cho một nền tảng có trong request, nên bài không thể đăng như đã gửi.	Kết nối tài khoản trong mục Kết nối của dashboard, hoặc bỏ nền tảng đó khỏi `platforms`. Gửi lại y nguyên request thì không thể thành công. Nếu cứ sau mỗi bài đăng được là lại gặp lỗi này, nền tảng đang hạn chế tài khoản và kết nối lại sẽ không gỡ được, hãy đọc `message`.
`location_required`	400	Tài khoản Google của Profile có nhiều địa điểm Google Business, request không chỉ định địa điểm nào, và lúc kết nối Google Business chưa chọn địa điểm mặc định.	Truyền `location_id` (`message` liệt kê các id, còn `GET /v1/gbp/locations` trả kèm tên), hoặc chọn địa điểm mặc định khi kết nối Google Business.
`upstream_error`	502	Đường xuất bản của MADIAD Hub thực sự gặp sự cố: lỗi mạng, hoặc lỗi 5xx khi đang gửi bài. Vấn đề về nội dung và quyền không nằm ở đây, chúng trả `400` hoặc `409`.	Lỗi tạm thời. An toàn để retry toàn bộ request chỉ khi bạn đã gửi `Idempotency-Key` để lần retry không tạo bài đăng trùng.
`upstream_timeout`	502	Việc đăng bài vượt quá thời gian MADIAD Hub chờ, nên chưa xác định được kết quả: bài có thể đã lên. Lượt đăng không được hoàn, và `Idempotency-Key` bạn gửi đã được chốt vào câu trả lời này, nên gửi lại cùng key sẽ nhận đúng kết quả này chứ không tạo bài thứ hai.	Đừng retry ngay. Hãy kiểm tra lịch sử đăng hoặc kiểm tra trực tiếp trên nền tảng trước; nếu quyết định gửi lại thì dùng một `Idempotency-Key` MỚI.
`internal_error`	500 (hiếm khi 502)	Lỗi chưa được xử lý bên trong MADIAD Hub (lỗi database, exception ngoài dự kiến). Hiếm gặp và không phải do bạn gây ra. Một vài thao tác có thể trả về 502 thay vì 500.	Coi cả hai là retryable: thử lại với backoff. Nếu vẫn lặp lại, liên hệ hỗ trợ kèm chi tiết request.

Xem Idempotency để hiểu Idempotency-Key ngăn tạo bài đăng trùng lặp khi retry như thế nào, và Rate limit để hiểu giới hạn theo phút đứng sau rate_limited.

Khi nào nên retry?

Hãy phân nhánh theo mã trạng thái, đừng bao giờ dựa vào câu chữ trong message:

Trạng thái	Ý nghĩa	Retry y nguyên request?
`4xx`	Vấn đề nằm ở request, ở nội dung, hoặc ở trạng thái tài khoản.	Không. Phải sửa gì đó trước, gửi lại y nguyên sẽ hỏng y như cũ.
`429`	Gửi quá nhanh, hoặc đã hết hạn mức.	Có, sau khoảng thời gian ghi trong `Retry-After`.
`5xx`	Việc đăng bài thất bại ở phía Hub.	Có, kèm backoff, và nhớ gửi `Idempotency-Key` để lần retry không tạo bài trùng. Ngoại lệ duy nhất là `upstream_timeout`: kết quả chưa xác định, phải kiểm tra trước khi gửi lại.

Tới trước ngày 07/08/2026, mọi lỗi phát sinh khi đăng bài đều được báo là 502, kể cả những lỗi vĩnh viễn như caption vượt giới hạn hoặc Profile chưa kết nối tài khoản. Vì vậy các automation retry theo 5xx đã retry cả những request không bao giờ thành công được. Nếu tích hợp của bạn đang lách chỗ này bằng cách đọc message, giờ có thể bỏ đoạn đó và phân nhánh theo mã trạng thái.

Lỗi không có envelope chuẩn

Một request multipart quá lớn có thể bị chặn ở tầng biên mạng trước khi tới được MADIAD Hub, phản hồi khi đó là 413 Request Entity Too Large dạng thuần (không có envelope JSON). Hãy chuyển sang gửi ảnh bằng photo_urls[]: MADIAD Hub sẽ tự tải ảnh về phía máy chủ, nên request body luôn nhỏ gọn bất kể ảnh lớn đến đâu. Nén file ảnh lại cũng là một cách nếu chỉ vượt nhẹ.

Bắt đầu

Khái niệm

Tích hợp

Tham chiếu API

Bảng mã lỗi

Khi nào nên retry?

Lỗi không có envelope chuẩn

​Bảng mã lỗi

​Khi nào nên retry?

​Lỗi không có envelope chuẩn

Bảng mã lỗi

Khi nào nên retry?

Lỗi không có envelope chuẩn