Các lỗi có mã trạng thái trả về là 400, 401, 402, 403, 404, 429, 500, 502, 503 hoặc 504. Thành công có mã trạng thái trả về là
200. Xem tại đây để biết chi tiết.
- Trường
errorschứa mảng các lỗi, mỗi mạng xã hội có lỗi một mục. actioncho biết loại lỗi được trả về.- Trường
statusở cấp cao nhất sẽ là “error” nếu lệnh gọi API thất bại. Ví dụ, đối với lệnh gọi /post, nếu tất cả các mạng xã hội đăng bài thành công, trườngstatussẽ là “success”, ngược lại trường status sẽ là “error”. - Trường
codechứa mã lỗi tham chiếu của Ayrshare. - Trường
messagelà chi tiết cụ thể của lỗi.
Xử lý lỗi
Bạn nên xử lý mọi phản hồi lỗi và thực hiện hành động phù hợp. Lỗi xảy ra nếu:- Mã trả về phản hồi không phải là
200 - Trạng thái JSON của phản hồi là
error
400 Bad Request.
400 Bad Request:
Hạn mức bài đăng hàng tháng
Code 106 — Vượt quá hạn mức bài đăng hàng tháng (HTTP 429) Profile đã dùng hết hạn mức bài đăng hàng tháng./post trả về lỗi này cho các request đăng bài mới, kể cả các request lên lịch bài đăng. Các request bài đăng khác, chẳng hạn lấy, xóa hoặc thử lại một bài đăng, hay số liệu phân tích bài đăng, cũng trả về lỗi này cho đến khi hạn mức được đặt lại. Bài đăng đã lên lịch đến giờ đăng trong lúc hạn mức đã hết cũng thất bại với mã này. Đây không phải giới hạn tốc độ. Chờ vài phút sẽ không giúp được gì.
Thông thường, toàn bộ phản hồi chính là lỗi:
errors của bài đăng. Điều này cũng có thể xảy ra với bài đăng mới nếu hạn mức hết trong lúc bài đang được gửi. Hãy kiểm tra code: 106 ở cả hai chỗ.
Hành động: Kiểm tra monthlyPostCount và monthlyPostQuota bằng Chi tiết User Profile. Hạn mức được đặt lại vào ngày 1 mỗi tháng (UTC). Đổi gói sẽ đặt lại bộ đếm của Primary Profile ngay lập tức. Các lần đăng bài thất bại cũng được tính, vì vậy hãy dừng mọi cơ chế tự động thử lại các bài đăng liên tục thất bại. Xem Tôi có thể đăng và gọi API bao nhiêu lần? để biết chi tiết.
Lỗi nội dung trùng lặp hoặc tương tự
Trước khi bài đăng được gửi tới mạng xã hội, Ayrshare so sánh nó với các bài đăng khác của bạn và từ chối nội dung giống hệt hoặc gần giống với mã137. Đây là kiểm tra riêng của Ayrshare, nên một bài đăng có thể bị từ chối ngay cả khi mạng xã hội vẫn cho phép. Kiểm tra này không áp dụng cho mọi nền tảng — xem các ngoại lệ bên dưới.
scheduleDate của nó làm tâm — 24 giờ trước và 24 giờ sau. Vì khung này nhìn cả về phía trước lẫn phía sau, một bài đăng có thể bị từ chối vì một bài được lên lịch sau nó, chứ không chỉ trước nó.
Phạm vi so sánh.
- Việc đối chiếu được thực hiện theo từng hồ sơ người dùng và theo từng nền tảng. Cùng một nội dung gửi tới X/Twitter và LinkedIn không bị coi là trùng lặp, và hai hồ sơ người dùng khác nhau cũng không xung đột với nhau.
- X/Twitter là ngoại lệ, nhưng chỉ áp dụng cho các bản trùng lặp giống hệt: một bài đăng giống hệt cũng được kiểm tra trên mọi hồ sơ người dùng thuộc cùng một tài khoản, vì X không cho phép đăng cùng một nội dung trên nhiều handle. Các nội dung gần giống (tương tự) vẫn chỉ giới hạn trong một hồ sơ người dùng duy nhất — chính hồ sơ đã đăng bài.
- Pinterest, Reddit và Telegram không được kiểm tra trùng lặp.
Mã lỗi dành riêng cho Instagram
Các mã lỗi sau cung cấp chi tiết cụ thể về các thất bại khi đăng lên Instagram, thay thế lỗi 138 chung khi có thể. Code 435 — Instagram Rate Limit (HTTP 429) Các tài khoản Instagram chuyên nghiệp (Business / Creator) chịu giới hạn 50 bài đăng cuộn trong 24 giờ trên Content Publishing API của Meta (tài khoản cá nhân hoàn toàn không thể đăng qua API và do đó không bao giờ chạm giới hạn này). Khi vượt quá giới hạn, Meta trả về lỗi rate-limit. Ayrshare cũng đưa racode: 435 khi endpoint publish của Meta trả về HTTP 429 trực tiếp hoặc khi sub-code lỗi cơ bản (1390008) cho biết throttle bài đăng / bình luận.
Retry-After, giá trị (tính bằng giây) được truyền qua trường details — hãy đợi ít nhất khoảng thời gian đó trước khi gửi lại.
Code 436 — Instagram Media Processing Timeout (HTTP 400)
Instagram mất quá nhiều thời gian để xử lý media đã tải lên. Điều này có thể xảy ra với các tệp video lớn hoặc trong thời gian máy chủ của Meta chịu tải cao.
instagramOptions.trialParams được cung cấp trên request /post nhưng graduationStrategy bị thiếu, null hoặc là chuỗi rỗng. Trial reels yêu cầu graduation strategy rõ ràng — xem Trial Reels.
instagramOptions.trialParams.graduationStrategy thành "MANUAL" hoặc "SS_PERFORMANCE" và thử lại, hoặc gỡ bỏ trialParams nếu bạn không có ý định đăng trial reel.
Code 448 — Instagram Trial Reels: Invalid graduationStrategy (HTTP 400)
Được trả về khi graduationStrategy có mặt nhưng không đúng chính xác "MANUAL" hoặc "SS_PERFORMANCE". Việc kiểm tra phân biệt chữ hoa/thường — các giá trị như "manual" hoặc "ss_performance" sẽ bị từ chối. Trường details phản ánh đầu vào bị từ chối (được cắt bớt còn 64 ký tự) để hỗ trợ gỡ lỗi.
graduationStrategy chính xác là "MANUAL" hoặc "SS_PERFORMANCE" (chữ hoa, kiểu string).
Code 449 — Instagram Trial Reels: Incompatible Media (HTTP 400)
Được trả về khi media hoặc dạng bài đăng không đủ điều kiện cho trial reel. Trial reels phải là một video .mp4 hoặc .mov duy nhất — carousels (nhiều hơn một URL), stories (instagramOptions.stories: true), và các định dạng không phải video đều bị từ chối. Trường details cho biết trường hợp con nào đã kích hoạt.
.mp4 hoặc .mov duy nhất mà không có cờ stories: true. Bỏ các mục mediaUrls bổ sung, hoặc gỡ bỏ trialParams nếu bạn định đăng bài carousel/story thông thường.
Code 258 — Instagram Account-State Error (HTTP 400)
Một thất bại chung liên quan đến trạng thái tài khoản Instagram với thông báo gốc “Error with Instagram.” Điều này xuất hiện khi Meta từ chối request do trạng thái của tài khoản Instagram đã kết nối chứ không phải do nội dung bài đăng.
error_subcode cơ bản của Meta là 2207085 (“Generic Internal Error”), đây là lỗi tạm thời từ phía Meta. Ayrshare tự động thử đăng lại trong tối đa khoảng 50 giây trước khi trả về lỗi, và phản hồi đặt retryAvailable: true. Phản hồi không đặt relink: true — việc liên kết lại không khắc phục được tình trạng này. Khi Meta cung cấp fbtrace_id, giá trị này được trả về trong details:
2207085, hãy thử đăng lại sau vài phút — đây là tình trạng từ phía Meta và thường tự hết, việc liên kết lại không khắc phục được. Chỉ khi lỗi kéo dài quá 24-48 giờ, hãy yêu cầu người dùng huỷ liên kết và liên kết lại tài khoản Instagram trong Social Accounts, cấp tất cả các quyền được yêu cầu, hoặc liên hệ bộ phận hỗ trợ của Meta kèm fbtrace_id trong details. Đối với các lỗi trạng thái tài khoản khác, xác minh tài khoản Instagram đang ở trạng thái tốt trên Meta và thử lại.
Có thể thử lại (Retry Available)
Đôi khi các mạng xã hội gặp lỗi không thể phục hồi, chẳng hạn như họ đang gặp sự cố máy chủ, và lệnh gọi cuối cùng thất bại ngay cả sau nhiều lần thử lại. Trong những trường hợp đó, hệ thống của chúng tôi sẽ xác định xem lỗi có thể thử lại hay không và nếu có, trườngretryAvailable sẽ là true.
Lỗi Audio Instagram Reels
Các mã này bao gồm việc đính kèm nhạc vào một Reel Instagram vớiinstagramOptions.audioConfiguration, và các endpoint tìm kiếm audio và tra cứu audio.
Mã 518 xuất hiện trên
postIds[].warnings[], không phải errors[]. Instagram cho phép một bản nhạc mỗi Reel, nên khi cả audioConfiguration và audioName được gửi, audioConfiguration thắng và audioName bị loại bỏ. Phản hồi vẫn là status: "success" với HTTP 200 — hãy coi 518 là thông tin tham khảo và đừng xử lý nó như một thất bại. Cảnh báo được lồng trên mục postIds của nền tảng đó thay vì ở cấp cao nhất, và mang feature: "audioName".Việc xác thực âm lượng báo mã
101 chung, không phải một mã riêng. audioVolume và videoVolume phải là số nguyên từ 0 đến 100. Một số thập phân, một chuỗi số như "80", một số ngoài phạm vi, hoặc một null tường minh trả về code: 101 với giới hạn được nêu tên trên details, trước khi Instagram được gọi. Hãy bỏ qua trường thay vì gửi null.Lỗi Private-Reply Automation (Comment DM)
Các mã này xuất hiện trên các automation kích hoạt theo bình luận (comment_keyword) khi private reply mang DM không thể gửi được. Chúng hiển thị dưới dạng hàng activity status: "failed" với lý do trên actionResults[].errorDetails.
Không mã nào được tự động thử lại — Instagram Send API không có idempotency key, do đó một lần thử lại tự động có nguy cơ chuyển DM hai lần. Cách xử lý khác nhau tuỳ theo mã (xem Hành động bên dưới): hầu hết là vĩnh viễn cho bình luận cụ thể đó, 492 cần kết nối lại tài khoản, và 493 tự hết khi giới hạn theo giờ được đặt lại.
Mã 491 bao gồm nhiều nguyên nhân mà Instagram không phân biệt, và 490 là ngoại lệ hẹp. Instagram trả về một lỗi chung cho một bình luận cũ hơn 7 ngày, một bình luận đã nhận được một reply (chỉ cho phép duy nhất một private reply mỗi bình luận), một bình luận đã bị xoá, và người bình luận chặn message requests. Tất cả các trường hợp này đều báo
491.490 chỉ được báo trong trường hợp hẹp hơn khi Instagram nhận diện thẳng ID bình luận là không hợp lệ thay vì trả về bucket chung — do đó một bình luận bị xoá có thể xuất hiện dưới dạng hoặc 490 hoặc 491 tuỳ vào cái Instagram trả về.Vì API không tách biệt các trường hợp này, luôn đọc errorDetails: nó mang lời giải thích riêng của Instagram, thường cụ thể về nguyên nhân.Mã
489 được dành riêng và hiện không được trả về. Nó được giữ cho trường hợp “bình luận này đã có một reply”, trường hợp mà Instagram hiện không hiển thị dưới dạng một tín hiệu riêng — trường hợp đó hiện báo 491. Nó chỉ được liệt kê ở đây để số không bị dùng lại.Một kết nối thực sự hết hạn hoặc không hợp lệ không nằm trong phạm vi này. Nếu credential Instagram được lưu đã hết hạn, hàng activity sẽ là
status: "auth_error" chứ không phải failed, và kết nối lại tài khoản là cách khắc phục đúng. Ngoại trừ 492 — một quyền còn thiếu, được cấp bằng cách kết nối lại tài khoản — các mã ở trên là điều kiện cấp bình luận và không bao giờ có nghĩa là “kết nối lại”.GET /automations/:id/activity trả về. Lý do của Instagram nằm trên actionResults[].errorDetails:
details:
errorDetails ở đó mang cùng chuỗi mà envelope đặt trong details.
Hành động:
- 490, 491, 495 — các điều kiện theo từng bình luận. Chúng không thể khôi phục cho bình luận cụ thể đó, và không có lần thử lại nào giúp được; automation vẫn hoạt động bình thường với bình luận mới tiếp theo. Đọc
errorDetailsđể biết lý do Instagram nêu. - 492 — kết nối lại tài khoản Instagram, cấp mọi quyền được yêu cầu. Đây là bản sửa cấp tài khoản và nếu không sẽ ảnh hưởng đến mọi bình luận.
- 493 — không cần hành động gì ngoài việc chờ; giới hạn theo giờ tự đặt lại. Không được thử lại tự động, do đó DM cho bình luận đó không được gửi.
- 494 — lỗi cấu hình nội bộ, không phải điều kiện phía khách hàng. Liên hệ hỗ trợ nếu tái diễn.
Trạng thái
sent không đảm bảo việc chuyển tin. Tách biệt với các thất bại ở trên, một private reply mà Instagram chấp nhận (status: "sent") vẫn có thể bị âm thầm loại bỏ khi thiết lập Message requests trên Instagram của người nhận chặn người lạ — điều này hoàn toàn không sinh ra mã lỗi nào. Xem Automation DM đã Gửi nhưng Không được Chuyển.Lỗi Tùy chọn Thread và Phương tiện
Các mã này được trả về khi một tùy chọn không thể được áp dụng cho bài đăng — thường gặp nhất trên một X Thread hoặc thread trên Threads, nơi các tùy chọn bạn gửi áp dụng cho toàn bộ thread.182— Video không đáp ứng yêu cầu về thời lượng. Video ngắn hơn mức tối thiểu của mạng xã hội hoặc dài hơn mức tối đa của nó. Phản hồi nêu rõ thời lượng thực tế của video cùng với mức tối thiểu và tối đa được áp dụng, nên hãy so sánh ba con số này để xác nhận bạn đã chạm giới hạn nào. Trên X, khoảng tiêu chuẩn là 0,5 đến 140 giây (2 phút 20 giây); để đăng một video dài hơn, hãy đặtlongVideo: true, tùy chọn này nâng mức tối đa lên 4 giờ cho một tài khoản được X chấp thuận đăng video dài. Các mạng xã hội khác có giới hạn riêng — xem nguyên tắc phương tiện cho mạng bạn đang đăng.101— Thiếu hoặc sai tham số. Trên Threads, mã này được trả về khiallowCountriesđược gửi từ một tài khoản mà Meta chưa cho phép áp dụng giới hạn địa lý. Không phần nào của bài đăng hoặc thread được xuất bản. Hãy kiểm traisEligibleForGeoRestrictionstrên /user trước khi gửi tùy chọn này.111— X đã từ chối bài đăng. Đây là mã chung cho một thất bại từ X không có mã cụ thể hơn, nên hãy đọcdetailstrong phản hồi — nó mang thông báo của chính X và là thứ cho bạn biết nguyên nhân. Một nguyên nhân phổ biến là một tùy chọn mà tài khoản không được cấp quyền sử dụng, chẳng hạnsubscribersOnlymà không có X Subscriptions, hoặclongPosttrên một bài đăng đơn lẻ mà không có X Premium; trong trường hợp đó, hãy bỏ tùy chọn hoặc kiểm tra các quyền của tài khoản. Các lỗi kết nối và các lỗi khác từ phía X cũng xuất hiện dưới dạng111, và những lỗi đó đáng để thử lại thay vì thay đổi yêu cầu của bạn.Lưu ý rằnglongPostkhông phải là một nguyên nhân của111trên một thread — ở đó nó bị bỏ qua kèm một cảnh báo và thread vẫn được xuất bản. Xem Bài đăng dài.275— Bài đăng quá dài để xuất bản dưới dạng thread. Việc chia nội dung đã tạo ra nhiều hơn mức tối đa 30 bài đăng. Hãy rút ngắn nội dung hoặc chia nó thành các thread riêng biệt. Việc tự thêm thread breaks với\n\nsẽ không giúp được ở đây — mỗi điểm ngắt tạo thêm một bài đăng, nên nó có thể đẩy số lượng vượt giới hạn xa hơn.
Một tùy chọn mà tài khoản của bạn không thể sử dụng sẽ làm thất bại toàn bộ bài đăng thay vì bị bỏ
qua. Trên một thread, điều này có nghĩa là không phần nào của thread được xuất bản — các phần đã
được đăng sẽ được xóa giúp bạn. Việc xóa là nỗ lực tốt nhất: nếu mạng xã hội từ chối một lệnh xóa,
phần đó có thể vẫn còn được xuất bản, nên hãy kiểm tra thread và gỡ bất kỳ phần nào còn sót lại.
Trước đây một số tùy chọn này bị âm thầm loại bỏ trên thread và thread được xuất bản mà không có
chúng.
Lỗi Link Session
Các mã 501 đến 513 thuộc về liên kết mạng xã hội: tạo một liên kết với Tạo một Link Session, và mở một liên kết. Chúng mang"action": "link session". Các mã 500-series khác trên trang này không liên quan — 514 đến 518 là
audio Instagram Reels.
Hãy khớp trên
code dạng số, không phải trên văn bản thông báo, vốn có thể thay đổi hoặc được dịch.
Trang của bạn có thể nghe được mã nào trong số này. Với một origin được đặt, một cửa sổ bật
lên liên kết gửi các sự kiện hoàn tất liên kết đến trang
của bạn, và 513 có thể đến theo cách đó dưới dạng một connect:error. 501, 502 và 503 thì
không thể: một liên kết đã chết bị từ chối trước khi trang biết được nơi gửi sự kiện, nên người
dùng của bạn thấy lý do trên màn hình và trang của bạn nghe được connect:cancelled khi họ đóng
cửa sổ. Để phân biệt ba mã đó, hãy poll
Lấy một Link Session. 504 đến 510 là các sự từ chối của
chính lệnh POST và không bao giờ đến dưới dạng sự kiện, còn 511 và 512 được đưa ra trong khi
mạng xã hội đang gọi ngược lại, nên chúng xuất hiện ở đó thay vì trên trang của bạn.
Lỗi X/Twitter BYO Key
Các mã lỗi sau dành riêng cho các thao tác X/Twitter BYO (Bring Your Own) key: Code 272 - Failed to Verify BYO Twitter Identity (HTTP 400) Ayrshare không thể xác nhận danh tính X/Twitter của bạn bằng các consumer key BYO và các OAuth token được lưu tại thời điểm liên kết. Dạng phản hồi thay đổi tuỳ theo lệnh gọi nào đã kích hoạt nó; cả hai dạng đều ánh xạ đến ba trường hợp con dưới đây. Hãy xác minh trường hợp nào áp dụng bằng cách đăng nhập vào x.com với tài khoản sở hữu BYO Developer App. Đường đi post phát ra phản hồi tối thiểu:details mang chuỗi lỗi thô từ X:
details phản ánh gợi ý phía X và là tín hiệu đơn tin cậy nhất để biết trường hợp con nào dưới đây áp dụng.
Tài khoản bị đình chỉ. Đăng nhập vào x.com hiển thị thông báo đình chỉ. Hành động: Liên hệ với hỗ trợ của X. Liên kết lại sẽ không khôi phục quyền truy cập cho đến khi X phục hồi tài khoản.
Tài khoản bị khoá. Đăng nhập vào x.com hiển thị thử thách mở khoá (CAPTCHA, xác minh điện thoại, v.v.). Hành động: Hoàn tất thử thách mở khoá trên x.com, sau đó thử lại request. Không cần liên kết lại.
Không khớp danh tính hoặc key. Tài khoản X của bạn đang ở trạng thái tốt trên x.com, nhưng các consumer key BYO của bạn thuộc về một X Developer App khác với các OAuth token được lưu tại thời điểm liên kết. Hành động: Liên kết lại X trong Social Accounts và uỷ quyền với cùng tài khoản X sở hữu BYO Developer App.
Code 364 — X Rate Limit (HTTP 429)
X đã throttle một request được thực hiện bằng các BYO key của bạn. Đây là mã rate limit dùng chung của Ayrshare, và giờ đây nó bao gồm cả đường đọc bình luận X: Get Comments trả về mã này khi X áp rate limit cho lệnh đọc, trong khi trước đây một danh sách bình luận rỗng được trả về thay thế.
code: 416 khi tài khoản đã hết credit, vì vậy 416 không chỉ giới hạn ở việc đăng văn bản hay lấy dữ liệu phân tích. Quá trình tải lên thất bại trước khi bài đăng được xuất bản và không được thử lại — không lần thử lại nào có thể thành công cho đến khi tài khoản có credit.
x-access-level: read, xác nhận rằng Access Token của bạn được tạo với quyền chỉ đọc.
Hành động: Trong X Developer Console, cập nhật quyền app thành Read and write and Direct message, sau đó tạo lại Access Token trong Keys and tokens. Token mới sẽ kế thừa quyền đã cập nhật. Xem Hướng dẫn thiết lập X BYO Key để biết chi tiết.
Code 419 - Missing BYO Credentials (HTTP 400)
Các thao tác X/Twitter yêu cầu thông tin xác thực BYO API trong header của request. Ayrshare trả về code 419 khi cả hai header đều thiếu, và cũng khi chỉ có một trong cặp có mặt. Chuỗi message thay đổi tuỳ theo (các) header nào bị thiếu.
Khi cả X-Twitter-OAuth1-Api-Key và X-Twitter-OAuth1-Api-Secret đều thiếu:
X-Twitter-OAuth1-Api-Key và X-Twitter-OAuth1-Api-Secret trên mọi request tới X. Nếu bạn cung cấp một mà không có cái kia, request sẽ bị từ chối với cùng mã. Xem X BYO Keys Header Reference để biết danh sách header đầy đủ.
Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403)
Được trả về khi một request X/Twitter dựa vào đường đi OAuth cũ (non-BYO), vốn không còn được hỗ trợ. Truy cập X API hiện yêu cầu thông tin xác thực X Developer App của riêng bạn được cung cấp qua các header request.
X-Twitter-OAuth1-Api-Key và X-Twitter-OAuth1-Api-Secret trên mọi request tới X. Xem Hướng dẫn thiết lập X BYO Key để biết đầy đủ các bước thiết lập.
Lỗi Caption Enhancement
Code 441 — Caption Enhancement Failed (HTTP 502) Được trả về khi caption enhancement (ví dụshortenLinks) thất bại cho một hoặc nhiều nền tảng khi chuẩn bị bài đăng. Mỗi nền tảng bị ảnh hưởng xuất hiện trong mảng errors với source: "handlePostAdditions" và code: 441.
Khi chỉ một số nền tảng thất bại, các nền tảng khác vẫn đăng thành công và kết quả của chúng xuất hiện trong postIds. Trong trường hợp đó status ở cấp cao nhất là "error" nhưng postIds không rỗng — client nên coi status và errors[] là bổ sung cho nhau chứ không loại trừ lẫn nhau.
code: 441 ở cấp cao nhất với HTTP 502 và không có bài đăng nào được tạo:
- Nếu
postIdskhông rỗng (một số nền tảng đã đăng thành công), không gửi lại toàn bộ tập nền tảng — điều đó sẽ tạo bài đăng trùng lặp trên các nền tảng đã thành công. Thay vào đó, kiểm traerrors[]để xác định các nền tảng thất bại và thử lại request chỉ với các nền tảng đó, hoặc dựa vào luồng thử lại idempotent của riêng bạn. - Nếu
postIdsrỗng hoặc thiếu (thất bại hoàn toàn tại thời điểm lên lịch/đăng), thử lại toàn bộ request một cách an toàn. - Nếu thất bại vẫn tiếp diễn, gửi bài đăng mà không có cờ enhancement (ví dụ, bỏ
shortenLinks) hoặc liên hệ hỗ trợ.
Lỗi Media Fetch / Crawler Access
Code 499 — Ayrshare Media Probe Temporarily Unavailable (HTTP 503) Được trả về khi Ayrshare không thể hoàn tất quá trình kiểm tra media trước khi đăng vì không thể tiếp cận dịch vụ media-probe nội bộ hoặc dịch vụ này trả về phản hồi không hợp lệ. Đây là lỗi dịch vụ của Ayrshare, không phải bằng chứng cho thấy URL media, CDN, quy tắc user-agent hoặc cấu hìnhrobots.txt của bạn có vấn đề. Lỗi này mang theo retryAvailable: true; hãy thử lại nền tảng thất bại sau ít phút. Nếu một request multiplatform đã thành công một phần, chỉ thử lại các nền tảng được liệt kê trong errors[] để tránh đăng trùng lặp.
mediaUrls không hợp lệ, media không thể đọc được và một số thất bại upload/fetch qua mạng. Trước tiên hãy kiểm tra details được trả về nếu có. Đối với lỗi truy cập, hãy xác nhận rằng URL có thể truy cập công khai, vẫn còn hợp lệ đủ lâu để xuất bản, và không chặn các request từ xa. /media/urlExists chỉ thực hiện một kiểm tra khả năng tiếp cận HEAD; kết quả thành công ở đó không đảm bảo rằng quá trình kiểm tra media sâu hơn trước khi đăng hoặc crawler của mạng xã hội có thể tải xuống và xử lý tệp. Khi lỗi cụ thể là dịch vụ probe của chính Ayrshare không khả dụng, bạn sẽ nhận được code 499 có thể thử lại thay vì code 164.
Code 440 — Social Network Could Not Download Media (HTTP 400)
Được trả về khi crawler xuất bản của nền tảng không thể tải xuống mediaUrl bạn cung cấp — phổ biến nhất là do robots.txt hoặc quy tắc WAF / bot-fight đang chặn crawler (ví dụ, facebookexternalhit của Meta). Chuỗi details đến từ nền tảng thượng nguồn và thường là văn bản lỗi 2207052 của Meta/Instagram.
details thường chứa "Restricted by robots.txt" hoặc "HTTP error code 403". Mã 138 cũng được dùng cho các vấn đề tỷ lệ / định dạng và các lỗi Instagram chung khác, vì vậy biến thể media-fetch có thể nhận diện được bằng chuỗi details.
mediaUrl. API Threads không trả về các chuỗi chi tiết, vì vậy chẩn đoán thường yêu cầu kiểm tra lỗi Instagram 440 hoặc 138 xảy ra đồng thời trong cùng lần xuất bản.
robots.txt và lệnh xác minh.
Phương tiện Threads chưa sẵn sàng
Code 522 — Threads Media Not Ready to Publish (HTTP 400) Threads chưa hoàn tất việc chuẩn bị bài đăng khi Ayrshare cố gắng xuất bản nó. Threads có thể báo một bài đăng đã sẵn sàng vài giây trước khi thực sự chấp nhận việc xuất bản. Ayrshare chờ và thử lại tổng cộng tối đa 30 giây cho một bài đăng Threads, tính trên mọi phần của một thread nhiều phần, trước khi trả về lỗi này, vì vậy hầu hết các bài đăng như vậy giờ đây được xuất bản mà không gặp lỗi nào. Đây thường là sự cố tạm thời từ phía Threads và nội dung của bạn không phải là nguyên nhân. Bình luận, phản hồi và bình luận đầu tiên trên Threads cũng được chờ tương tự (bình luận đầu tiên có 30 giây riêng sau khi bài đăng được xuất bản), nhưng chúng không trả về mã 522. Với một thread nhiều phần, đối tượngcode: 522 không nằm trực tiếp trong errors: nó là mục cuối cùng trong mảng posts của lỗi Threads, và trạng thái HTTP 400 nêu trên chỉ áp dụng cho một bài đăng Threads đơn lẻ. noAutoRetry: true chỉ ngăn máy chủ MCP của Ayrshare tự động thử lại bài đăng; bạn vẫn có thể thử lại.
postIds. Nếu chưa có gì được xuất bản, hãy thử lại bài đăng bằng endpoint retry post. Nếu một nền tảng khác trong cùng bài đăng đã xuất bản thành công, thay vào đó hãy gửi một bài đăng mới chỉ đến Threads: retry post gửi lại payload gốc đến mọi nền tảng, điều này sẽ khiến các nền tảng đã thành công xuất bản lần thứ hai.
Thread nhiều phần: postIds rỗng không chứng minh rằng không có phần nào của thread đang hiển thị. Ayrshare sẽ xóa các phần đã được xuất bản khi một phần sau đó thất bại, nhưng nếu việc xóa thất bại, phần đó vẫn còn trên Threads. Trước khi thử lại một thread nhiều phần, hãy kiểm tra tài khoản Threads và xóa mọi phần vẫn còn ở đó, nếu không lần thử lại sẽ đăng chúng thêm lần nữa.
Giới hạn tốc độ Facebook Analytics
Code 444 — Facebook Page Analytics Rate Limit (HTTP 429) Được trả về khi một Facebook Page đã vượt quá giới hạn tốc độ per-Page của Meta trên endpoint analytics. Lỗi cơ bản của Meta là80001 (“There have been too many calls to this Page account.”). Page vẫn được liên kết và việc đăng bài vẫn tiếp tục hoạt động — chỉ việc fan-out analytics cho Page đó bị throttle.
Khi throttle được phát hiện cho một bài đăng đơn trong phản hồi /history/facebook hoặc analytics, mỗi bài đăng bị ảnh hưởng mang code: 444 tại facebook.code với errCode: 80001:
Xác minh danh tính Meta
Code 326 — Meta Identity Verification Required (HTTP 403) Được trả về khi Meta yêu cầu xác minh danh tính bổ sung cho tài khoản đã kết nối trước khi chấp nhận request. Điều này áp dụng trên các nền tảng Meta — Facebook, Instagram, Facebook Groups, Threads và Messenger. Kết nối lại tài khoản không giải quyết được điều này; quá trình xác minh phải được hoàn tất phía Meta.Chặn theo Tiêu chuẩn cộng đồng Facebook
Code 249 — Facebook Community Standards Block (HTTP 400) Được trả về khi Facebook chặn một bài đăng theo Tiêu chuẩn cộng đồng (Community Standards) của họ. Lệnh chặn có thể áp dụng cho tài khoản hoặc Trang Facebook, hoặc cho chính bài đăng. Facebook dùng cùng một lỗi gốc cho cả hai trường hợp và không cho biết trường hợp nào đang áp dụng. Trên thực tế, lệnh chặn thường được đặt lên tài khoản hoặc Trang, nên việc viết lại hay gửi lại nội dung thường không giúp ích. Giống như Hạn chế tài khoản Facebook (code 476), đây là kết quả thực thi phía Meta. Lỗi này không thể thử lại và không mang cờretryAvailable. Ở lần vi phạm đầu tiên, tài khoản vẫn được liên kết với Ayrshare và không cần liên kết lại; việc liên kết lại cũng không gỡ bỏ lệnh chặn. Vi phạm lặp lại thì khác, xem bên dưới.
Facebook không trả về lý do cụ thể thông qua API, vì vậy khách hàng phải kiểm tra trực tiếp trang Account Status của Facebook để xem lý do và kháng cáo. Khi Facebook cung cấp văn bản nguyên văn của riêng họ, Ayrshare đưa văn bản đó vào trường details. Ayrshare cũng gửi email thông báo cho chủ tài khoản khi phát hiện lệnh chặn.
Vi phạm Tiêu chuẩn cộng đồng lặp lại trên cùng một User Profile (hồ sơ người dùng) sẽ hủy liên kết tài khoản Facebook khỏi Ayrshare và đình chỉ User Profile đó.
code là 249, không theo nội dung message. Câu chữ của message có thể được tinh chỉnh theo thời gian, trong khi code thì ổn định.
Hành động: Đăng nhập vào Facebook, nhấp vào ảnh hồ sơ (góc trên bên phải), mở phần Help và chọn Account Status. Trợ lý hỗ trợ của Facebook ở đó cho biết lý do cụ thể (mà API không trả về) và cho phép bạn kháng cáo. Không yêu cầu người dùng liên kết lại tài khoản, vì việc liên kết lại không gỡ bỏ lệnh chặn ở cấp tài khoản hoặc Trang. Xem Tài khoản Facebook hoặc Instagram bị hạn chế để biết hướng dẫn khắc phục sự cố đầy đủ.
Hạn chế tài khoản Facebook
Code 476 — Facebook Account Restriction (HTTP 400) Được trả về khi một bài đăng lên Facebook thất bại vì Meta đã đặt hạn chế lên tài khoản (các subcode lỗi Meta2424009 và 1404078, hoặc ngôn từ hạn chế của Meta khi lỗi không mang subcode). Đây là hạn chế ở cấp tài khoản, không phải trục trặc xuất bản tạm thời — nó không thể thử lại và không mang cờ retryAvailable. Việc gửi lại cùng bài đăng sẽ không thành công cho đến khi hạn chế được giải quyết với Meta. Tài khoản vẫn được liên kết với Ayrshare; không cần liên kết lại.
Meta không trả về lý do hạn chế cụ thể thông qua API, vì vậy khách hàng phải kiểm tra trực tiếp trang Account Status của Meta để xem lý do và kháng cáo. Khi Meta cung cấp văn bản nguyên văn của riêng nó, Ayrshare đưa ra trường details. Ayrshare cũng gửi email thông báo cho chủ tài khoản khi phát hiện hạn chế.
Lỗi chuyển đổi định dạng hình ảnh
Ayrshare tự động chuyển đổi hình ảnh WebP, HEIC, HEIF và AVIF sang JPEG trước khi đăng lên các nền tảng không chấp nhận chúng (Instagram, LinkedIn, TikTok, Google My Business, Threads và Snapchat cho WebP; tất cả các nền tảng cho HEIC, HEIF và AVIF). Chuyển đổi chạy minh bạch tại thời điểm gửi. Ba lỗi dưới đây chỉ xảy ra khi bản thân pipeline chuyển đổi không thể hoàn tất; nếu hình ảnh nguồn đã ở định dạng được hỗ trợ, không có chuyển đổi nào được thực hiện và các mã này sẽ không xuất hiện. Code 450 — Image Format Conversion Failed (HTTP 400) Hình ảnh đã được tải xuống nhưng không thể mã hoá lại thành JPEG. Nguyên nhân phổ biến nhất là tệp nguồn bị hỏng, định dạng nội bộ không mong đợi bên trong container, hoặc hình ảnh vượt quá giới hạn kích thước chuyển đổi.mediaUrl nguồn trực tiếp trong trình duyệt để xác nhận nó hiển thị. Nếu có, hãy xuất lại hình ảnh sang JPEG hoặc PNG sạch và thử lại bài đăng.
Code 451 — Image Download Failed for Conversion (HTTP 400)
Pipeline chuyển đổi không thể lấy hình ảnh nguồn. Các nguyên nhân điển hình bao gồm phản hồi 4xx/5xx từ nguồn, timeout mạng, chuỗi chuyển hướng vượt giới hạn hop, hoặc URL phân giải đến địa chỉ không công khai (bị chặn bởi bảo vệ SSRF). Trường details, khi có mặt, mang chuỗi nguyên nhân cơ bản.
mediaUrl có thể truy cập công khai (không auth, không bị robots.txt chặn, phân giải qua HTTPS). Nếu URL chuyển hướng, đảm bảo đích đến cuối cùng cũng công khai và không nằm trên mạng riêng.
Code 452 — Converted Image Upload Failed (HTTP 500)
Chuyển đổi thành công nhưng Ayrshare không thể đưa JPEG đã chuyển đổi lên bucket lưu trữ tạm thời của nó. Đây là thất bại nội bộ phía Ayrshare và có thể thử lại.
mediaUrl và dấu thời gian gần đúng.
Lỗi upload tạm thời của YouTube
Các mã lỗi sau cung cấp tín hiệu cụ thể cho các thất bại upload YouTube thường là tạm thời và an toàn để thử lại. Cả hai phản hồi đều bao gồmretryAvailable: true, vì vậy các tích hợp có thể phân nhánh dựa trên boolean đó thay vì mã trạng thái HTTP.
Hầu hết các phản hồi code: 176 trước đây cho upload YouTube giờ được định tuyến đến 453 (timeout tạm thời) hoặc 454 (dịch vụ tạm thời không khả dụng), cả hai với retryAvailable: true. Nếu tích hợp của bạn lọc theo HTTP 500 để thử lại upload YouTube, hãy chuyển sang lọc theo trường retryAvailable trong body phản hồi.
Code 453 — YouTube Upload Timed Out (HTTP 504)
Được trả về khi pipeline ingest YouTube của Google timeout khi chấp nhận upload. Đây thường là tạm thời và tự giải quyết trong vòng một hoặc hai phút.
retryAvailable trong body phản hồi thay vì trạng thái HTTP để phát hiện các thất bại có thể thử lại. Bạn có thể sử dụng endpoint retry post để gửi lại cùng payload.
Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503)
Được trả về khi endpoint upload của YouTube trả về trạng thái 5xx, hoặc khi kết nối tới YouTube bị reset hoặc timeout ở tầng socket (ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT). Các điều kiện này là tạm thời.
retryAvailable trong body phản hồi thay vì trạng thái HTTP để phát hiện các thất bại có thể thử lại.
Lỗi Thumbnail YouTube Code 307
Mã307 được trả về khi một thumbNail YouTube tuỳ chỉnh không thể được áp dụng. Khi bản thân video đăng thành công, điều này không làm bài đăng thất bại — kết quả YouTube giữ status: "success" và đưa ra thất bại bổ sung trong mảng warnings (feature: "thumbnail", code: 307). Sub-object thumbnail cũ được giữ lại để tương thích ngược.
Nguyên nhân phổ biến nhất là kênh YouTube chưa được xác minh. Khi một kênh chưa hoàn tất xác minh điện thoại, YouTube trả về 403 thượng nguồn với thông báo chung "The authenticated user doesn't have permissions to upload and set custom video thumbnails". Ngôn từ đó nghe giống vấn đề OAuth, nhưng trong thực tế nó hầu như luôn là vấn đề xác minh, vì vậy hãy xác minh kênh trước. Liên kết lại tài khoản YouTube là nguyên nhân thứ yếu.
warnings không nghiêm trọng (status cấp cao nhất vẫn là "success"). Điều này đúng bất kể vấn đề được phát hiện khi nào:
- Bắt được trước khi upload. Khi xác thực trước xuất bản có thể xác định rõ ràng thumbnail không hợp lệ (loại tệp sai, đã xác nhận trên 2MB, hoặc URL không thể truy cập), Ayrshare bỏ qua thumbnail, vẫn xuất bản video, và báo lý do chính xác trong
warnings— vì vậy bạn tránh được một lần upload chắc chắn thất bại và nhận được thông báo rõ ràng hơn so với nhà cung cấp sẽ trả về. - Bắt được sau khi upload. Khi thất bại chỉ có thể phát hiện được sau khi YouTube xử lý request (ví dụ
403kênh chưa xác minh, hoặc413cho hình ảnh quá kích thước), video đã live và thất bại được đưa ra trong cùng mảngwarnings.
status: "success" + warnings được hiển thị ở đầu phần này.
Hành động: Xác minh kênh YouTube của bạn tại https://www.youtube.com/verify (xác minh điện thoại). Nếu kênh đã được xác minh và thumbnail vẫn thất bại, hãy huỷ liên kết và liên kết lại tài khoản YouTube trong Social Accounts và cấp tất cả các quyền. Xem YouTube Thumbnail Not Applied (Unverified Channel) để có hướng dẫn xử lý sự cố đầy đủ.
Lỗi uỷ quyền Google Business Profile
Code 519 — Google Business Profile Authorization Service Temporarily Unavailable (HTTP 503) Được trả về khi Ayrshare không thể hoàn tất việc làm mới token uỷ quyền Google, do endpoint token của Google phản hồi chậm hoặc trả về một thất bại tạm thời. Việc làm mới được tự động thử lại trước khi mã này được trả về, và phản hồi mang theoretryAvailable: true, vì vậy các tích hợp có thể phân nhánh dựa trên boolean đó thay vì mã trạng thái HTTP. Tài khoản vẫn được kết nối — đây là tình trạng tạm thời trên dịch vụ uỷ quyền của Google, không phải kết nối bị hỏng.
Mọi thao tác Google Business Profile đều làm mới uỷ quyền trước tiên, vì vậy bất kỳ thao tác nào trong số đó đều có thể trả về mã này — đăng bài, đọc lịch sử bài đăng, cập nhật dữ liệu địa điểm, lấy tài khoản đã kết nối, liệt kê đánh giá, và trả lời một đánh giá.
Hầu hết các phản hồi code: 227 trước đây trên các đường dẫn này giờ được định tuyến đến 519 với retryAvailable: true. Mã 227 yêu cầu người dùng kết nối lại tài khoản, điều này chưa bao giờ giải quyết được một thất bại làm mới tạm thời — bản thân uỷ quyền vẫn nguyên vẹn trong suốt quá trình. Nếu tích hợp của bạn lọc theo 227 để nhắc liên kết lại Google Business Profile, hãy chuyển sang phân nhánh trên trường retryAvailable trong body phản hồi và thử lại với backoff thay vào đó.
details mang lý do mà Google báo cáo, hoặc — khi việc làm mới timeout cục bộ mà không có body phản hồi từ Google — một bản tóm tắt các lần thử đã thực hiện và thời gian đã trôi qua.
Hành động: Thử lại request với exponential backoff. Phân nhánh trên trường retryAvailable trong body phản hồi thay vì trạng thái HTTP để phát hiện các thất bại có thể thử lại.
Cảnh báo công bố AI trên Pinterest
Code 521 — Pinterest AI Disclosures Not Applied (HTTP 200) Cảnh báo, không phải lỗi. Được trả về khipinterestOptions.aiDisclosures không hợp lệ, ví dụ một giá trị không xác định hoặc sai chữ hoa/chữ thường. Thông qua REST API, một giá trị không phải là mảng chuỗi cũng trả về 521. Pin vẫn được xuất bản, nhưng Ayrshare không gửi bất kỳ công bố AI nào đến Pinterest. MCP server và GraphQL API kiểm tra kiểu giá trị trước, nên các giá trị sai định dạng như một danh sách chứa một số sẽ bị từ chối ở đó trước khi đăng. Cảnh báo xuất hiện trên postIds[].warnings[] của mục Pinterest, không phải errors[], và mang feature: "pinterestOptions.aiDisclosures". Các giá trị được chấp nhận là AI_MODIFIED và SYNTHETIC_PERFORMER.
Lỗi đăng bài Reddit
Code 442 — Reddit Banned Subreddit (HTTP 400) Được trả về khi tài khoản đã bị cấm đăng vào subreddit đích. Đây không thể thử lại — bài đăng sẽ không thành công nếu gửi lại nguyên trạng. Thông báo bao gồm tên subreddit bị ảnh hưởng (ví dụ:r/news).
r/news).
Lỗi kiểm duyệt
Code 438 — Moderation Input Rejected (HTTP 400) Được trả về bởiPOST /validate/moderation khi nhà cung cấp AI từ chối đầu vào được cung cấp — ví dụ, một loại tệp không được hỗ trợ. Đây là vấn đề đầu vào của request, không phải thất bại xử lý tạm thời.
So sánh mã 438 với mã 331. Mã 331 bao gồm cùng kịch bản kiểm duyệt nhưng đại diện cho thất bại xử lý thực sự phía nhà cung cấp (HTTP 500, thông báo “There was an issue with the AI processing. Please try again.”). Mã 331 là thất bại phía server tạm thời mà bạn có thể thử lại, trong khi mã 438 chỉ ra rằng chính đầu vào đã bị từ chối và phải được sửa trước khi thử lại.
Lỗi làm mới ủy quyền LinkedIn
Mã 524 — LinkedIn từ chối làm mới token (HTTP 500) Được trả về khi LinkedIn từ chối làm mới ủy quyền do sự cố với cấu hình LinkedIn của ứng dụng, không phải do tài khoản của người dùng. Kết nối LinkedIn của người dùng vẫn hợp lệ, vì vậy liên kết lại không khắc phục được lỗi này. Phản hồi không bao gồm trườngresolution.relink và có retryAvailable: false vì thử lại không khắc phục được lỗi.
Bất kỳ thao tác LinkedIn nào làm mới ủy quyền trước đều có thể trả về mã này, chẳng hạn như đăng bài sau khi access token đã hết hạn.
Nếu LinkedIn liên tục làm mới thất bại vì lý do tạm thời, Ayrshare sẽ thử lại rồi trả về mã 119 (“There was an issue connecting with LinkedIn. Please try again.”) thay vào đó. Bạn có thể thử lại sau một cách an toàn với mã 119; mã 524 không được khắc phục bằng cách thử lại.
Lỗi LinkedIn Analytics
Code 475 — Re-link LinkedIn Profile for Analytics (HTTP 403) Được trả về bởiPOST /analytics/post và POST /analytics/social cho một hồ sơ LinkedIn cá nhân (member) đã được liên kết trước khi member analytics được triển khai. Các hồ sơ này thiếu các scope member analytics của LinkedIn (r_member_postAnalytics, r_member_profileAnalytics), vì vậy LinkedIn từ chối request analytics. Việc đăng bài không bị ảnh hưởng.
475 trong khoảng ~5-10 phút trước khi analytics thành công.
Lỗi bình luận TikTok
Code 288 — TikTok Comment Deferred / Post Still Processing (HTTP 400) TikTok xử lý video một cách bất đồng bộ, vì vậyid của bài đăng mới xuất bản là "pending" cho đến khi webhook post.publish.publicly_available của TikTok phân giải id video thực. Một request get-comments, bình luận, hoặc trả lời đối với một bài đăng vẫn đang được xử lý (hoặc bài có id là "failed") bị từ chối trước bất kỳ lệnh gọi nào tới TikTok và trả về mã 288 thay vì một thất bại chung.
tikTokPublished hoặc poll /history cho đến khi id bài đăng là id video số đã được phân giải. First comment được đăng tự động khi bài đăng được phân giải, vì vậy không cần thử lại. Đối với bài đăng "failed", thông báo thay vào đó ghi chú rằng video không thể xuất bản và hành động sẽ không chạy.
Lỗi Story Đã hết hạn hoặc Không khả dụng
Code 485 — Bình luận Instagram / Facebook Story và Phân tích Instagram Story (HTTP 404 khi là mã đại diện) Story có thể trở nên hết hạn hoặc không khả dụng sau cửa sổ khả dụng của chúng. Sau cửa sổ đó, bình luận hoặc insight không thể được truy xuất. Code485 nhận diện:
- các nhánh Instagram và Facebook Story đã hết hạn hoặc không khả dụng từ get-comments; và
- một nhánh Instagram Story đã hết hạn hoặc không khả dụng từ
POST /analytics/post.
485. Client nên so khớp code dạng số, không phải văn bản thông báo chính xác, vốn có thể thay đổi hoặc được dịch.
Trên một lệnh đọc đa nền tảng nơi có ít nhất một nền tảng khác thành công, nhánh thất bại xuất hiện trong mảng errors[] ở cấp cao nhất trong khi các nền tảng hoạt động tốt trả về bình thường. Phản hồi tổng thể là HTTP 200 với status: "partial" ở cấp cao nhất (xem Đọc Đa nền tảng & Thành công Một phần cho bình luận và phân tích).
Ví dụ Thành công Một phần của Get Comments
Ví dụ Thành công Một phần của Post Analytics
status: "error" ở cấp cao nhất và bao gồm mảng errors[] đầy đủ. Code đại diện 485 ánh xạ sang HTTP 404; các mã đại diện khác sử dụng ánh xạ HTTP riêng của chúng.
Hành động: Coi code 485 như một tín hiệu rằng bình luận hoặc insight Story được yêu cầu không thể được truy xuất. So khớp trên code thay vì rút ra kết luận về thất bại vĩnh viễn, khả năng thử lại, hoặc liên kết tài khoản từ văn bản thông báo.
Dịch thông báo lỗi
Phản hồi thông báo lỗi của API có thể được tự động dịch sang ngôn ngữ bạn chọn. Điều này hữu ích nếu bạn muốn hiển thị lỗi trực tiếp cho người dùng bằng ngôn ngữ ưa thích của họ. Xem tại đây nếu bạn muốn chọn ngôn ngữ của trang liên kết mạng xã hội. Trong header, hãy bao gồm:Language_Code là một trong các mã ngôn ngữ khả dụng.
Ví dụ, phần sau sẽ dịch lỗi sang tiếng Pháp.