Ayrshare Error Codes - Ayrshare API Documentation

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, 502, 503, or 504. 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 272 - Failed to Verify BYO Twitter Identity (HTTP 400) Ayrshare could not confirm your X/Twitter identity using your BYO consumer keys and the OAuth tokens stored at link time. The response shape varies by which call triggered it; both forms map to the same three sub-cases below. Verify which one applies by logging into x.com with the account that owns the BYO Developer App. The post path emits a minimal response:

{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}

The analytics path emits a longer, self-documenting message and may include a details field carrying X’s raw error string:

{
  "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"
}

When present, details mirrors the X-side hint and is the most reliable single signal for which sub-case below applies. Account suspended. Logging into x.com shows a suspension notice. Action: Contact X support. Re-linking will not restore access until X reinstates the account. Account locked. Logging into x.com presents an unlock challenge (CAPTCHA, phone verification, etc.). Action: Complete the unlock challenge on x.com, then retry the request. No re-link is required. Identity or key mismatch. Your X account is in good standing on x.com, but your BYO consumer keys belong to a different X Developer App than the OAuth tokens stored at link time. Action: Re-link X under Social Accounts and authorize with the same X account that owns the BYO Developer App. 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. Code 419 - Missing BYO Credentials (HTTP 400) X/Twitter operations require BYO API credentials in the request headers. Ayrshare returns code 419 when both headers are missing, and also when only one of the pair is present. The message string varies depending on which header(s) are missing. When both X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret are missing:

{
  "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"
}

When only one of the pair is present (for example, the key without the secret):

{
  "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"
}

Action: Send both X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret on every X-bound request. If you provide one without the other, the request is rejected with the same code. See the X BYO Keys Header Reference for the full header list.

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.

YouTube Transient Upload Errors

The following error codes provide specific signals for YouTube upload failures that are typically transient and safe to retry. Both responses include retryAvailable: true, so integrations can branch on that boolean rather than on the HTTP status code. Most prior code: 176 responses for YouTube uploads now route to 453 (transient timeout) or 454 (transient service unavailable), both with retryAvailable: true. If your integration filters on HTTP 500 to retry YouTube uploads, switch to filtering on the retryAvailable field on the response body. Code 453 — YouTube Upload Timed Out (HTTP 504) Returned when Google’s YouTube ingest pipeline timed out while accepting the upload. This is typically transient and resolves on its own within a minute or two.

{
  "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"
    }
  ]
}

Action: Retry the post after 1–2 minutes with exponential backoff. Branch on the retryAvailable field on the response body rather than HTTP status to detect retryable failures. You can use the retry post endpoint to resubmit the same payload. Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503) Returned when YouTube’s upload endpoint returns a 5xx status, or when the connection to YouTube was reset or timed out at the socket layer (ECONNRESET, ETIMEDOUT, ESOCKETTIMEDOUT). These conditions are transient.

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 454,
      "message": "YouTube upload service temporarily unavailable. Please retry.",
      "retryAvailable": true,
      "platform": "youtube"
    }
  ]
}

Action: Retry the post with exponential backoff. Branch on the retryAvailable field on the response body rather than HTTP status to detect retryable failures. You can use the retry post endpoint to resubmit the same payload.

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.

Documentation Index

​Handling Errors

​Instagram-Specific Error Codes

​Retry Available

​X/Twitter BYO Key Errors

​Caption Enhancement Errors

​Media Fetch / Crawler Access Errors

​Facebook Analytics Rate Limit

​Image Format Conversion Errors

​YouTube Transient Upload Errors

​Error Message Translation

Handling Errors

Instagram-Specific Error Codes

Retry Available

X/Twitter BYO Key Errors

Caption Enhancement Errors

Media Fetch / Crawler Access Errors

Facebook Analytics Rate Limit

Image Format Conversion Errors

YouTube Transient Upload Errors

Error Message Translation