Skip to main content

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.

The REST API will include a response with a list of errors if applicable.
Errors have a returned status code of 400, 401, 402, 403, 404, 429, 500, or 502. Success has a returned status code 200. See here for details.
Each API call can return different errors depending on the specific request and any issues encountered at the social network. The error response will contain details about what went wrong during the API call. For example, a post that is considered a duplicate by Twitter and Facebook would return the following response. 
{
  "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"
}
Please note:
  • The errors field contains the array of errors, one per social network that had an error.
  • The action refers to the type of error returned.
  • The top-level status field will be “error” if the API call failed. For example, for a /post call if all social network posting were successful the status field will be “success”, else the status field will be “error”.
  • The code field contains the Ayrshare reference error code.
  • The message field is the specific details of the error.

​
Handling Errors

You should handle any error responses and take the appropriate action. An error occurred if:
  • The response return code is not 200
  • The JSON response status is error
For example, if Facebook link was removed by your user - they changed their password or removed Ayrshare’s access - the following response would occur when posting with a 400 Bad Request response code. 
{
  "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"
}
An action might be to notify your user via your dashboard, text or email. Another example is if the posted Instagram image is the wrong dimensions or ratio with a 400 Bad Request response code: 
{
  "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?"
}
An action might be resending the images with the correct ratio.

​
Instagram-Specific Error Codes

The following error codes provide specific details about Instagram posting failures, replacing the generic error 138 where possible. Code 435 — Instagram Rate Limit (HTTP 429) Instagram professional (Business / Creator) accounts are subject to a 50-post rolling 24-hour limit on Meta’s Content Publishing API (personal accounts cannot publish via API at all and therefore never hit this limit). When the cap is exceeded, Meta returns a rate-limit error. Ayrshare also surfaces code: 435 when Meta’s publish endpoint returns HTTP 429 directly or when the underlying error subcode (1390008) indicates a post / comment throttle. 
{
  "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"
    }
  ]
}
Action: Wait for the rate limit window to reset before retrying. When Meta supplies a Retry-After header, the value (in seconds) is passed through on the details field — wait at least that long before resubmitting. Code 436 — Instagram Media Processing Timeout (HTTP 400) Instagram took too long to process the uploaded media. This can happen with large video files or during periods of high load on Meta’s servers. 
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 436,
      "message": "Instagram media processing timed out. Please try posting again.",
      "retryAvailable": true,
      "platform": "instagram"
    }
  ]
}
Action: Retry the post using the retry post endpoint. If the issue persists, try reducing the media file size. Code 447 — Instagram Trial Reels: Missing graduationStrategy (HTTP 400) Returned when instagramOptions.trialParams is provided on a /post request but graduationStrategy is missing, null, or an empty string. Trial reels require an explicit graduation strategy — see Trial Reels. 
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 447,
      "message": "Instagram trial reels require instagramOptions.trialParams.graduationStrategy (\"MANUAL\" or \"SS_PERFORMANCE\").",
      "platform": "instagram"
    }
  ]
}
Action: Set instagramOptions.trialParams.graduationStrategy to either "MANUAL" or "SS_PERFORMANCE" and retry, or remove trialParams if you did not intend to publish a trial reel. Code 448 — Instagram Trial Reels: Invalid graduationStrategy (HTTP 400) Returned when graduationStrategy is present but is not exactly "MANUAL" or "SS_PERFORMANCE". The check is case-sensitive — values like "manual" or "ss_performance" are rejected. The details field echoes the rejected input (truncated to 64 characters) to aid debugging. 
{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 448,
      "message": "Invalid Instagram graduationStrategy. Must be \"MANUAL\" or \"SS_PERFORMANCE\".",
      "details": "Received: manual",
      "platform": "instagram"
    }
  ]
}
Action: Send graduationStrategy as exactly "MANUAL" or "SS_PERFORMANCE" (uppercase, string type). Code 449 — Instagram Trial Reels: Incompatible Media (HTTP 400) Returned when the media or post shape is not eligible for a trial reel. Trial reels must be a single .mp4 or .mov video — carousels (more than one URL), stories (instagramOptions.stories: true), and non-video extensions are all rejected. The details field disambiguates which sub-case fired. 
{
  "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"
    }
  ]
}
Action: Submit a single .mp4 or .mov video URL with no stories: true flag. Drop additional mediaUrls entries, or remove trialParams if you intended a regular carousel/story post.

​
Retry Available

Sometimes the social networks have a unrecoverable error, such as their are having server issues, and the call ultimately fails even after numerous retries. In those cases, our system will determine if the error is retryable and if so, the retryAvailable field will be true. 
{
  "retryAvailable": true
}
You can then retry the call with the same payload. If it is a post you can use the retry post endpoint.

​
X/Twitter BYO Key Errors

The following error codes are specific to X/Twitter BYO (Bring Your Own) key operations: Code 416 — X Credits Depleted (HTTP 402) Your X Developer account has no API credits loaded. All X API calls require credits. 
{
  "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"
}
Action: Go to console.x.com → Billing → Credits and purchase credits. Even $5 is enough for hundreds of API calls. Code 417 — OAuth 1.0a App Permissions (HTTP 403) Your X Access Token does not have the correct permissions for the requested operation. 
{
  "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"
}
You may also see the response header x-access-level: read, which confirms your Access Token was generated with read-only permissions. Action: In the X Developer Console, update your app permissions to Read and write and Direct message, then regenerate your Access Token under Keys and tokens. The new token will inherit the updated permissions. See the X BYO Key Setup Guide for details.

​
Caption Enhancement Errors

Code 441 — Caption Enhancement Failed (HTTP 502) Returned when a caption enhancement (for example shortenLinks) fails for one or more platforms while preparing a post. Each affected platform appears in the errors array with source: "handlePostAdditions" and code: 441. When only some platforms fail, the other platforms still post successfully and their results appear in postIds. In that case the top-level status is "error" but postIds is non-empty — clients should treat status and errors[] as complementary rather than mutually exclusive. 
{
  "status": "error",
  "errors": [
    {
      "platform": "twitter",
      "status": "error",
      "source": "handlePostAdditions",
      "code": 441,
      "message": "Caption enhancement failed for twitter. <underlying error>. Post was not sent to this platform."
    }
  ],
  "postIds": [
    {
      "status": "success",
      "id": "...",
      "postUrl": "...",
      "platform": "bluesky"
    }
  ],
  "id": "..."
}
If all platforms fail enhancement, the response is a top-level code: 441 with HTTP 502 and no post is created: 
{
  "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. <underlying error>"
    }
  ]
}
Action: Caption enhancement failures are typically transient (the underlying shortener or enhancement service returned an error).
  • If postIds is non-empty (some platforms posted successfully), do not resubmit the full platform set — that would duplicate the post on the successful platforms. Instead, inspect errors[] to identify the failed platforms and retry the request with only those platforms, or rely on your own idempotent retry flow.
  • If postIds is empty or missing (total failure at schedule/post time), safely retry the full request.
  • If the failure persists, submit the post without the enhancement flag (for example, drop shortenLinks) or contact support.

​
Media Fetch / Crawler Access Errors

Code 440 — Social Network Could Not Download Media (HTTP 400) Returned when the platform’s publishing crawler cannot download the mediaUrl you provided — most commonly because robots.txt or a WAF / bot-fight rule is blocking the crawler (for example, Meta’s facebookexternalhit). The details string comes from the upstream platform and is often the Meta/Instagram error 2207052 text. 
{
  "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) Fallback code for Instagram media-fetch failures when the upstream response is less specific than the one that triggers code 440. The details string typically contains "Restricted by robots.txt" or "HTTP error code 403". Code 138 is also used for aspect-ratio / format issues and other generic Instagram errors, so the media-fetch variant is identifiable by the details string. 
{
  "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 Returned when Threads publishing fails. Most commonly caused by the same media-fetch issue as codes 440 / 138 when publishing to both platforms with the same mediaUrl. The Threads API does not return detail strings, so diagnosis usually requires checking for a co-occurring Instagram 440 or 138 in the same publish. 
{
  "status": "error",
  "errors": [{
    "status": "error",
    "code": 379,
    "message": "Error posting to Threads.",
    "action": "post",
    "platform": "threads"
  }],
  "postIds": [],
  "id": "..."
}
Action: See Meta Media Crawler Blocked for full troubleshooting, including robots.txt snippets and a verification command.

​
Facebook Analytics Rate Limit

Code 444 — Facebook Page Analytics Rate Limit (HTTP 429) Returned when a Facebook Page has exceeded Meta’s per-Page rate limit on the analytics endpoint. The underlying Meta error is 80001 (“There have been too many calls to this Page account.”). The Page remains linked and publishing continues to work — only the analytics fan-out for that Page is throttled. When the throttle is detected for a single post in a /history/facebook or analytics response, each affected post carries code: 444 at facebook.code with errCode: 80001: 
{
  "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": "..."
}
Action: Wait a few minutes and retry. Meta’s per-Page rate-limit window typically resolves within the hour without any action on the Page. Do not prompt the user to relink the account — this is a transient throttle on Meta’s side, not an authorization failure.
If you previously handled this condition as code: 161 (“Facebook authorization error … unlink and re-link”), update your integration to recognize code: 444 and retry with backoff instead of initiating a relink flow. The 161 classification was corrected in April 2026.

​
Image Format Conversion Errors

Ayrshare automatically converts WebP, HEIC, and AVIF images to JPEG before posting to platforms that don’t accept them (Instagram, LinkedIn, TikTok, Google My Business, Threads, and Snapchat for WebP; all platforms for HEIC and AVIF). Conversion runs transparently at send time. The three errors below fire only when the conversion pipeline itself can’t complete; if the source image is already in a supported format, no conversion is attempted and these codes will not surface. Code 450 — Image Format Conversion Failed (HTTP 400) The image was downloaded but could not be re-encoded as JPEG. Most common causes are a corrupt source file, an unexpected internal format inside the container, or an image that exceeds the conversion size cap. 
{
  "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"
    }
  ]
}
Action: Open the source mediaUrl directly in a browser to confirm it renders. If it does, re-export the image to a clean JPEG or PNG and retry the post. Code 451 — Image Download Failed for Conversion (HTTP 400) The conversion pipeline could not fetch the source image. Typical causes include a 4xx/5xx response from the origin, a network timeout, a redirect chain that exceeds the hop limit, or a URL that resolves to a non-public address (blocked by the SSRF guard). The details field, when present, carries the underlying cause string. 
{
  "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"
    }
  ]
}
Action: Confirm the mediaUrl is publicly reachable (no auth, no robots.txt blocks, resolves over HTTPS). If the URL redirects, ensure the final destination is also public and not on a private network. Code 452 — Converted Image Upload Failed (HTTP 500) Conversion succeeded but Ayrshare could not stage the converted JPEG to its temporary storage bucket. This is an internal failure on the Ayrshare side and is retryable. 
{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 452,
      "message": "An error occurred uploading the converted image. Please try again.",
      "platform": "tiktok"
    }
  ]
}
Action: Retry the post. If the error persists across multiple retries, contact support with the mediaUrl and approximate timestamp.

​
Error Message Translation

The API error message response can be automatically translated to the language of your choice. This is useful if you want to display the error directly to your user in their preferred language. See here if you want to choose the language of the social linking page. In the header include: 
"Translate-Error-Message": "Language_Code"
Where the Language_Code is one of the available language codes. For example, the following will translate the error to French. 
"Translate-Error-Message": "fr" // Translate to French
Our system will automatically detect the error message language.