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:
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, phản hồi bổ sung đặt relink: true và retryAvailable: true, và thông báo hướng dẫn người dùng huỷ liên kết và liên kết lại tài khoản Instagram, cấp tất cả các quyền:
2207085, 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, sau đó thử lại bài đăng. Đố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 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 416 — X Credits Depleted (HTTP 402)
Tài khoản X Developer của bạn không có credit API nào được nạp. Tất cả các lệnh gọi X API đều yêu cầu 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 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ốngmediaUrl 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.
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.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 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 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. Bạn có thể sử dụng endpoint retry post để gửi lại cùng payload.
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 đă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 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.
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.
