> ## Documentation Index > Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Mã lỗi Ayrshare > Các mã lỗi cụ thể do Ayrshare trả về. REST API sẽ bao gồm phản hồi với danh sách các lỗi nếu có. 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](/errors/errors-http) để biết chi tiết. Mỗi lệnh gọi API có thể trả về các lỗi khác nhau tuỳ vào request cụ thể và bất kỳ vấn đề nào gặp phải tại mạng xã hội. Phản hồi lỗi sẽ chứa chi tiết về những gì đã xảy ra trong lệnh gọi API. Ví dụ, một bài đăng bị Twitter và Facebook coi là trùng lặp sẽ trả về phản hồi sau. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 110, "message": "Status is a duplicate.", "post": "Today is a great day", "platform": "twitter" }, { "action": "post", "status": "error", "code": 107, "message": "Facebook Error: This status update is identical to the last one you posted. Try posting something different, or delete your previous update.", "platform": "facebook" } ], "postIds": [], "id": "6APU4qqI7XO7JM3BOy6B" } ``` Xin lưu ý: ### 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: Ví dụ, nếu liên kết Facebook bị người dùng gỡ bỏ - họ đổi mật khẩu hoặc xoá quyền truy cập của Ayrshare - phản hồi sau sẽ xảy ra khi đăng bài với mã phản hồi `400 Bad Request`. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 161, "message": "Facebook authorization error. This can occur if your Facebook security changes. Try unlinking and re-linking Facebook or contact us for assistance.", "platform": "facebook" } ], "postIds": [], "id": "gh7SyTpeD2CQAMxWk3oh", "post": "A great Facebook Posts" } ``` Một hành động có thể là thông báo cho người dùng qua dashboard, tin nhắn hoặc email. Một ví dụ khác là nếu hình ảnh Instagram được đăng có kích thước hoặc tỷ lệ sai với mã phản hồi `400 Bad Request`: ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 138, "message": "Instagram Error: There was an issue posting to Instagram. The submitted image with aspect ratio ('1440/2158',) cannot be published. Please submit an image with a valid aspect ratio.", "platform": "instagram" } ], "postIds": [], "id": "Jxe2nMM3FmEvMXFSY3g4", "post": "Is this a good image?" } ``` Một hành động có thể là gửi lại hình ảnh với đúng tỷ lệ. ### 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](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) 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 ra `code: 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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "rate limit", "status": "error", "code": 435, "message": "Instagram rate limit reached. Please wait before retrying your post.", "details": "Retry-After: 3600", "platform": "instagram" } ] } ``` **Hành động:** Đợi cho khung thời gian rate limit được đặt lại trước khi thử lại. Khi Meta cung cấp header `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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 436, "message": "Instagram media processing timed out. Please try posting again.", "retryAvailable": true, "platform": "instagram" } ] } ``` **Hành động:** Thử lại bài đăng bằng endpoint [retry post](/apis/post/retry-post). Nếu vấn đề vẫn tồn tại, hãy thử giảm kích thước tệp media. **Code 447 — Instagram Trial Reels: Missing graduationStrategy (HTTP 400)** Được trả về khi `instagramOptions.trialParams` được cung cấp trên request [`/post`](/apis/post/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](/apis/post/social-networks/instagram#trial-reels). ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 447, "message": "Instagram trial reels require instagramOptions.trialParams.graduationStrategy (\"MANUAL\" or \"SS_PERFORMANCE\").", "platform": "instagram" } ] } ``` **Hành động:** Đặt `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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 448, "message": "Invalid Instagram graduationStrategy. Must be \"MANUAL\" or \"SS_PERFORMANCE\".", "details": "Received: manual", "platform": "instagram" } ] } ``` **Hành động:** Gử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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 449, "message": "Instagram trial reels must be a single video (.mp4 or .mov) — carousels and stories are not supported.", "details": "Carousels are not supported.", "platform": "instagram" } ] } ``` **Hành động:** Gửi một URL video `.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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 258, "message": "Error with Instagram.", "platform": "instagram" } ] } ``` Khi `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: ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 258, "message": "Error with Instagram. Please unlink and relink your Instagram account, granting all permissions, then retry.", "relink": true, "retryAvailable": true, "platform": "instagram" } ] } ``` **Hành động:** Đối với trường hợp con `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](https://app.ayrshare.com/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ường `retryAvailable` sẽ là `true`. ```json theme={"system"} { "retryAvailable": true } ``` Sau đó bạn có thể thử lại lệnh gọi với cùng payload. Nếu đó là một bài đăng, bạn có thể sử dụng endpoint [retry post](/apis/post/retry-post). ### 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](https://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: ```json theme={"system"} { "status": "error", "code": 272, "message": "Failed to verify BYO Twitter identity", "platform": "twitter" } ``` Đường đi analytics phát ra thông báo dài hơn, tự giải thích và có thể bao gồm trường `details` mang chuỗi lỗi thô từ X: ```json theme={"system"} { "action": "post", "status": "error", "code": 272, "message": "There is an issue authorizing your X/Twitter account. Login to x.com to verify your account status and then try unlinking Twitter and relinking on the social accounts page.", "resolution": { "relink": true, "platform": "twitter" }, "details": "The user used for authentication is suspended" } ``` Khi có mặt, `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. ```json theme={"system"} { "status": "error", "code": 416, "message": "Your enrolled account does not have any credits to fulfill this request. Purchase credits at console.x.com.", "platform": "twitter" } ``` **Hành động:** Đi tới [console.x.com](https://console.x.com) → Billing → Credits và mua credit. Ngay cả \$5 cũng đủ cho hàng trăm lệnh gọi API. **Code 417 — OAuth 1.0a App Permissions (HTTP 403)** X Access Token của bạn không có quyền phù hợp cho thao tác được yêu cầu. ```json theme={"system"} { "status": "error", "code": 417, "message": "Your client app is not configured with the appropriate oauth1 app permissions. Set app to 'Read and write and Direct message', then regenerate your Access Token.", "platform": "twitter" } ``` Bạn cũng có thể thấy header phản hồi `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](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting) để 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: ```json theme={"system"} { "action": "x_credentials_required", "status": "error", "code": 419, "message": "X/Twitter operations require your own API credentials. Missing: X-Twitter-OAuth1-Api-Key, X-Twitter-OAuth1-Api-Secret. Please provide your X Developer App credentials in the request headers. See https://docs.ayrshare.com/x-api-setup for setup instructions.", "resolution": { "docs": "https://docs.ayrshare.com/x-api-setup" }, "platform": "twitter" } ``` Khi chỉ có một trong cặp có mặt (ví dụ, key mà không có secret): ```json theme={"system"} { "action": "x_credentials_required", "status": "error", "code": 419, "message": "You provided X-Twitter-OAuth1-Api-Key but not X-Twitter-OAuth1-Api-Secret. OAuth 1.0a requires both. Missing: X-Twitter-OAuth1-Api-Secret. See https://docs.ayrshare.com/x-api-setup for setup instructions.", "resolution": { "docs": "https://docs.ayrshare.com/x-api-setup" }, "platform": "twitter" } ``` **Hành động:** Gửi cả `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](/dashboard/connect-social-accounts/x-twitter-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. ```json theme={"system"} { "status": "error", "code": 423, "message": "X (Twitter) API access now requires your own API credentials. Include X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret headers in your request. Setup guide: https://docs.ayrshare.com/dashboard/connect-social-accounts/x-twitter-byo-keys", "platform": "twitter" } ``` **Hành động:** Cấu hình một X Developer App và gửi các header `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](/dashboard/connect-social-accounts/x-twitter-byo-keys) để 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`](/apis/post/post)) 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. ```json theme={"system"} { "status": "error", "errors": [ { "platform": "twitter", "status": "error", "source": "handlePostAdditions", "code": 441, "message": "Caption enhancement failed for twitter. . Post was not sent to this platform." } ], "postIds": [ { "status": "success", "id": "...", "postUrl": "...", "platform": "bluesky" } ], "id": "..." } ``` Nếu **tất cả** các nền tảng thất bại enhancement, phản hồi là `code: 441` ở cấp cao nhất với HTTP `502` và không có bài đăng nào được tạo: ```json theme={"system"} { "status": "error", "action": "post", "code": 441, "message": "Caption enhancement failed. See error details for affected platforms.", "errors": [ { "platform": "twitter", "status": "error", "source": "handlePostAdditions", "code": 441, "message": "Caption enhancement failed for twitter. " } ] } ``` **Hành động:** Các thất bại caption enhancement thường là tạm thời (dịch vụ rút gọn hoặc enhancement bên dưới trả về lỗi). * **Nếu `postIds` khô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 tra `errors[]` để 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 `postIds` rỗ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ố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. ```json theme={"system"} { "status": "error", "errors": [{ "action": "post", "code": 440, "message": "The social network could not download media from this URL (for example Instagram/Meta error 2207052). Ensure the file is publicly reachable by the platform's crawlers (e.g. facebookexternalhit), via media bucket's robots.txt file, not only in a browser.", "details": "Media download has failed.: The media could not be fetched from the provided URI...", "platform": "instagram", "status": "error" }], "postIds": [], "id": "..." } ``` **Code 138 — Instagram Media Fetch Blocked (HTTP 400)** Mã dự phòng cho các thất bại lấy media của Instagram khi phản hồi thượng nguồn ít cụ thể hơn so với cái kích hoạt mã 440. Chuỗi `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`. ```json theme={"system"} { "status": "error", "errors": [{ "retryAvailable": true, "status": "error", "code": 138, "details": "Media download has failed.: The media could not be fetched from the provided URI. Video download failed with: HTTP error code 403. Restricted by robots.txt", "action": "post", "platform": "instagram", "message": "Instagram Error: Instagram cannot process your post at this time. Please try your post again." }], "postIds": [], "id": "..." } ``` **Code 379 — Threads Posting Error** Được trả về khi việc xuất bản Threads thất bại. Phổ biến nhất là do cùng vấn đề media-fetch như mã 440 / 138 khi xuất bản đến cả hai nền tảng với cùng `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. ```json theme={"system"} { "status": "error", "errors": [{ "status": "error", "code": 379, "message": "Error posting to Threads.", "action": "post", "platform": "threads" }], "postIds": [], "id": "..." } ``` **Hành động:** Xem [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked) để biết đầy đủ cách xử lý sự cố, bao gồm các đoạ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`](/apis/history/history-platform) hoặc [analytics](/apis/analytics/social), mỗi bài đăng bị ảnh hưởng mang `code: 444` tại `facebook.code` với `errCode: 80001`: ```json theme={"system"} { "status": "error", "facebook": { "action": "rate limit", "status": "error", "code": 444, "errCode": 80001, "message": "Facebook Page has hit its per-Page rate limit on the analytics endpoint. Please wait a few minutes and retry.", "pageId": "...", "id": "..." }, "httpErrorCode": 444, "lastUpdated": "...", "nextUpdate": "..." } ``` **Hành động:** Đợi vài phút và thử lại. Khung giới hạn tốc độ per-Page của Meta thường tự giải quyết trong vòng một giờ mà không cần bất kỳ hành động nào trên Page. **Không** yêu cầu người dùng liên kết lại tài khoản — đây là throttle tạm thời phía Meta, không phải thất bại uỷ quyền. Nếu bạn trước đây đã xử lý điều kiện này như `code: 161` ("Facebook authorization error … unlink and re-link"), hãy cập nhật tích hợp của bạn để nhận dạng `code: 444` và thử lại với backoff thay vì bắt đầu luồng liên kết lại. Phân loại `161` đã được sửa vào tháng 4 năm 2026. ### 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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 326, "message": "Meta is requesting additional identity verification for this account. Complete it at https://www.facebook.com/business-support-home and then retry. Reconnecting the account will not resolve this.", "platform": "facebook" } ] } ``` **Hành động:** Yêu cầu chủ tài khoản hoàn tất xác minh danh tính của Meta tại [Meta Business Support](https://www.facebook.com/business-support-home), sau đó thử lại request. **Không** yêu cầu người dùng liên kết lại tài khoản — việc liên kết lại sẽ không xoá bỏ yêu cầu nà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 Meta `2424009` 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ế. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 476, "message": "There is a Facebook restriction on your account. Log in to Facebook, click your profile picture (top-right), open the Help section and select Account Status. Meta's support assistant there surfaces the specific restriction reason (which the API doesn't return) and lets you appeal.", "details": "...", "platform": "facebook" } ] } ``` **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 Meta ở đó cho biết lý do hạn chế cụ thể và cho phép bạn kháng cáo. Vì hạn chế được Meta thực thi ở cấp tài khoản, mã này không thể thử lại — đừng xây dựng logic thử lại tự động xung quanh nó; hãy giải quyết hạn chế với Meta trước. ### 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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "image conversion", "status": "error", "code": 450, "message": "The image format could not be converted. The source image may be corrupt or inaccessible. Please verify the media URL and try again.", "platform": "instagram" } ] } ``` **Hành động:** Mở `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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "image conversion", "status": "error", "code": 451, "message": "The image could not be downloaded for format conversion.", "details": "HTTP 403 from origin", "platform": "linkedin" } ] } ``` **Hành động:** Xác nhậ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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "image conversion", "status": "error", "code": 452, "message": "An error occurred uploading the converted image. Please try again.", "platform": "tiktok" } ] } ``` **Hành động:** Thử lại bài đăng. Nếu lỗi vẫn tồn tại qua nhiều lần thử lại, hãy liên hệ hỗ trợ vớ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ồm `retryAvailable: 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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 453, "message": "YouTube upload timed out (Google ingest). This is typically transient; please retry in 1–2 minutes.", "retryAvailable": true, "platform": "youtube" } ] } ``` **Hành động:** Thử lại bài đăng sau 1–2 phút 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. Bạn có thể sử dụng endpoint [retry post](/apis/post/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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 454, "message": "YouTube upload service temporarily unavailable. Please retry.", "retryAvailable": true, "platform": "youtube" } ] } ``` **Hành động:** Thử lại bài đăng 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. Bạn có thể sử dụng endpoint [retry post](/apis/post/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. ```json theme={"system"} { "status": "success", "id": "", "thumbnail": { "action": "post", "status": "error", "code": 307, "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.", "details": "" }, "warnings": [ { "feature": "thumbnail", "code": 307, "message": "Your YouTube channel must be verified to set a custom thumbnail. Verify your channel at https://www.youtube.com/verify (phone verification). If your channel is already verified, try unlinking and re-linking your YouTube account to restore permissions.", "details": "" } ] } ``` Ayrshare cũng xác thực thumbnail trước khi xuất bản khi có thể: tệp phải là **PNG hoặc JPG/JPEG**, **2MB trở xuống**, và được phục vụ từ một **URL có thể truy cập**. Vấn đề thumbnail **không bao giờ làm bài đăng thất bại** — video luôn được xuất bản và thất bại luôn được đưa ra dưới dạng mục `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ụ `403` kênh chưa xác minh, hoặc `413` cho hình ảnh quá kích thước), video đã live và thất bại được đưa ra trong cùng mảng `warnings`. Trong cả hai trường hợp, phản hồi trông giống ví dụ `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](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](https://app.ayrshare.com/social-accounts) và cấp tất cả các quyền. Xem [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_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`). ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 442, "message": "You've been banned from posting to r/news. This post will not succeed on retry — remove it from your target subreddits.", "platform": "reddit" } ] } ``` **Hành động:** Xoá subreddit bị cấm khỏi các subreddit đích của bạn. Việc thử lại bài đăng không thay đổi sẽ không thành công. **Code 443 — Reddit Disallowed Word in Title (HTTP 400)** Được trả về khi một subreddit từ chối bài đăng vì tiêu đề chứa từ không được phép. Chỉnh sửa tiêu đề trước khi thử lại — gửi lại nguyên trạng sẽ không thành công. Thông báo bao gồm tên subreddit bị ảnh hưởng (ví dụ: `r/news`). ```json theme={"system"} { "status": "error", "errors": [ { "action": "post", "status": "error", "code": 443, "message": "r/news rejected this post because the title contains a disallowed word. Edit the title before retrying — retrying as-is will not succeed.", "platform": "reddit" } ] } ``` **Hành động:** Chỉnh sửa tiêu đề bài đăng để xoá từ không được phép, sau đó thử lại. ### Lỗi kiểm duyệt **Code 438 — Moderation Input Rejected (HTTP 400)** Được trả về bởi [`POST /validate/moderation`](/apis/post/post) 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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "moderation", "status": "error", "code": 438, "message": "There was an issue with the AI processing." } ] } ``` **Hành động:** Xác minh đầu vào kiểm duyệt hợp lệ và sử dụng loại tệp được hỗ trợ, sau đó gửi lạ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ởi [`POST /analytics/post`](/apis/analytics/post) và [`POST /analytics/social`](/apis/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. ```json theme={"system"} { "action": "authorization", "status": "error", "code": 475, "message": "Your LinkedIn profile is missing the analytics permissions. Please re-link your LinkedIn profile to enable analytics.", "resolution": { "relink": true, "platform": "linkedin" } } ``` **Hành động:** Yêu cầu chủ tài khoản liên kết lại hồ sơ LinkedIn của họ trong [Social Accounts](https://app.ayrshare.com/social-accounts) để cấp các scope analytics mới, sau đó thử lại request analytics. Sau khi liên kết lại, cho phép vài phút trước khi lỗi được xoá: Ayrshare cache lỗi này trong thời gian ngắn và LinkedIn cũng cache quyền của token, vì vậy một hồ sơ đã liên kết lại có thể tiếp tục trả về mã `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ậy `id` 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](/apis/comments/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. ```json theme={"system"} { "status": "error", "errors": [ { "action": "get", "status": "error", "code": 288, "message": "TikTok video is still processing; the action is deferred until the post is live.", "platform": "tiktok" } ] } ``` **Hành động:** Đợi cho đến khi TikTok xử lý xong, sau đó thử lại. Lắng nghe [webhook Scheduled Action `tikTokPublished`](/apis/webhooks/actions#scheduled-action) hoặc poll [/history](/apis/history/overview) cho đến khi `id` bài đăng là id video số đã được phân giải. [First comment](/apis/post/overview#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](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page). Trong header, hãy bao gồm: ```json theme={"system"} "Translate-Error-Message": "Language_Code" ``` Trong đó `Language_Code` là một trong các [mã ngôn ngữ](/iso-codes/language) khả dụng. Ví dụ, phần sau sẽ dịch lỗi sang tiếng Pháp. ```json theme={"system"} "Translate-Error-Message": "fr" // Translate to French ``` Hệ thống của chúng tôi sẽ tự động phát hiện ngôn ngữ của thông báo lỗi.