Ayrshare Error Codes

該当する場合、REST API はエラーのリストを含むレスポンスを返します。

エラーは 400、401、402、403、404、429、500、502、503、または 504 のステータスコードを返します。成功はステータスコード 200 を返します。詳細はこちらをご覧ください。

各 API 呼び出しは、リクエスト内容とソーシャルネットワーク側で発生した問題に応じて、異なるエラーを返す可能性があります。エラーレスポンスには、API 呼び出し中に何が問題だったかの詳細が含まれます。例えば、Twitter と Facebook で重複と判定された投稿は、次のようなレスポンスを返します。

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

注意事項:

errors フィールドには、エラーが発生した各ソーシャルネットワークごとに 1 つのエラーを持つ配列が含まれます。
action は返されたエラーの種類を示します。
API 呼び出しが失敗した場合、トップレベルの status フィールドは “error” になります。例えば /post 呼び出しで、すべてのソーシャルネットワークへの投稿が成功すれば status フィールドは “success”、そうでなければ status フィールドは “error” になります。
code フィールドには Ayrshare のリファレンスエラーコードが含まれます。
message フィールドはエラーの具体的な詳細です。

エラーのハンドリング

エラーレスポンスを処理し、適切なアクションを取るようにしてください。以下の場合、エラーが発生しています。

レスポンスのリターンコードが 200 ではない
JSON レスポンスの status が error

例えば、ユーザーが Facebook の連携を解除した場合(パスワードを変更した、Ayrshare のアクセスを削除した)、投稿時に次のレスポンスと 400 Bad Request レスポンスコードが返されます。

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

アクションとしては、ダッシュボード、テキスト、またはメールでユーザーに通知することが挙げられます。もう 1 つの例として、投稿した Instagram の画像の寸法や比率が不正な場合、400 Bad Request レスポンスコードで次のレスポンスが返されます。

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

アクションとしては、正しい比率で画像を再送信することが挙げられます。

Instagram 固有のエラーコード

以下のエラーコードは、Instagram 投稿失敗に関する具体的な詳細を提供し、可能な場合は汎用エラー 138 を置き換えます。 Code 435 — Instagram Rate Limit (HTTP 429) Instagram のプロフェッショナル(Business / Creator)アカウントは、Meta の Content Publishing API 上で、24 時間のローリングで 50 件までの投稿制限があります(個人アカウントは API 経由で公開できないため、この制限に達することはありません)。制限を超えると Meta はレート制限エラーを返します。Ayrshare は、Meta の公開エンドポイントが直接 HTTP 429 を返した場合、または内部エラーサブコード(1390008)が投稿/コメントのスロットルを示す場合にも code: 435 を表示します。

{
  "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: 再試行前にレート制限ウィンドウがリセットされるまでお待ちください。Meta が Retry-After ヘッダーを提供する場合、その値(秒)は details フィールドに含まれます — 少なくともその時間だけ待ってから再送信してください。 Code 436 — Instagram Media Processing Timeout (HTTP 400) Instagram のアップロード済みメディアの処理に時間がかかりすぎました。これは大きな動画ファイルの場合、または Meta のサーバー負荷が高い時間帯に発生することがあります。

{
  "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 post エンドポイントを使用して投稿を再試行してください。問題が継続する場合は、メディアファイルのサイズを縮小してみてください。 Code 447 — Instagram Trial Reels: Missing graduationStrategy (HTTP 400) /post リクエストで instagramOptions.trialParams が指定されているが、graduationStrategy が欠落、null、または空文字列の場合に返されます。トライアル Reels には明示的な graduation ストラテジーが必要です — 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: instagramOptions.trialParams.graduationStrategy を "MANUAL" または "SS_PERFORMANCE" のいずれかに設定して再試行するか、トライアル Reel を公開する意図がない場合は trialParams を削除してください。 Code 448 — Instagram Trial Reels: Invalid graduationStrategy (HTTP 400) graduationStrategy が存在するが、"MANUAL" または "SS_PERFORMANCE" と完全に一致しない場合に返されます。このチェックは大文字小文字を区別するため、"manual" や "ss_performance" などの値は拒否されます。デバッグを支援するため、details フィールドには拒否された入力(64 文字に切り詰め)がエコーされます。

{
  "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: graduationStrategy を厳密に "MANUAL" または "SS_PERFORMANCE"(大文字、文字列型)として送信してください。 Code 449 — Instagram Trial Reels: Incompatible Media (HTTP 400) メディアまたは投稿の形式がトライアル Reel の対象外の場合に返されます。トライアル Reels は単一の .mp4 または .mov 動画である必要があります — カルーセル(URL が複数)、ストーリー(instagramOptions.stories: true)、動画以外の拡張子はすべて拒否されます。details フィールドで、どのサブケースが発生したかを判別できます。

{
  "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: stories: true フラグを付けずに、単一の .mp4 または .mov 動画 URL を送信してください。追加の mediaUrls エントリを削除するか、通常のカルーセル/ストーリー投稿を意図していた場合は trialParams を削除してください。 Code 258 — Instagram Account-State Error (HTTP 400) 基本メッセージ「Error with Instagram.」を持つ、Instagram アカウント状態に関する一般的な失敗。投稿の内容ではなく、接続された Instagram アカウントの状態が原因で Meta がリクエストを拒否した場合に表示されます。

{
  "status": "error",
  "errors": [
    {
      "action": "post",
      "status": "error",
      "code": 258,
      "message": "Error with Instagram.",
      "platform": "instagram"
    }
  ]
}

基となる Meta の error_subcode が 2207085 の場合、レスポンスに relink: true および retryAvailable: true が追加され、Instagram アカウントの連携を解除して再連携し、すべての権限を付与するようメッセージがユーザーに指示します。

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

Action: 2207085 のサブケースでは、Social Accounts で Instagram アカウントの連携を解除して再連携し、すべての要求権限を付与するようユーザーに促し、その後投稿を再試行します。その他のアカウント状態エラーについては、Meta 上で Instagram アカウントが良好な状態であることを確認して再試行してください。

Retry Available

ソーシャルネットワーク側で回復不能なエラー(例: サーバーの問題)が発生し、複数回の再試行後でも呼び出しが最終的に失敗する場合があります。そのような場合、当社のシステムはエラーが再試行可能かを判断し、可能であれば retryAvailable フィールドを true に設定します。

{
  "retryAvailable": true
}

その後、同じペイロードで呼び出しを再試行できます。投稿の場合は、retry post エンドポイントを使用できます。

X/Twitter BYO Key エラー

以下のエラーコードは X/Twitter BYO(Bring Your Own)キー操作に固有です。 Code 272 - Failed to Verify BYO Twitter Identity (HTTP 400) Ayrshare は、BYO のコンシューマーキーと連携時に保存された OAuth トークンを使って X/Twitter の身元を確認できませんでした。レスポンスの形式はどの呼び出しがトリガーとなったかで異なりますが、両方の形式は下記の 3 つの同じサブケースにマッピングされます。BYO Developer App を所有するアカウントで x.com にログインし、どのケースに該当するかを確認してください。投稿パスは最小限のレスポンスを返します。

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

分析パスはより長く、自己文書化されたメッセージを返し、X の生のエラー文字列を含む details フィールドが付く場合があります。

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

details が存在する場合、X 側のヒントを反映しており、下記のどのサブケースに該当するかを判定する最も信頼できるシグナルとなります。 Account suspended. x.com にログインすると停止通知が表示されます。Action: X サポートに連絡してください。X がアカウントを復旧するまでは、再連携しても復元されません。 Account locked. x.com にログインするとロック解除チャレンジ(CAPTCHA、電話認証など)が表示されます。Action: x.com でロック解除チャレンジを完了してから、リクエストを再試行してください。再連携は不要です。 Identity or key mismatch. X アカウントは x.com 上で問題ありませんが、BYO のコンシューマーキーは、連携時に保存された OAuth トークンとは別の X Developer App に属しています。Action: Social Accounts で X を再連携し、BYO Developer App を所有する同じ X アカウントで認可してください。 Code 416 — X Credits Depleted (HTTP 402) X Developer アカウントに API クレジットが読み込まれていません。すべての X API 呼び出しにはクレジットが必要です。

{
  "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: console.x.com → Billing → Credits にアクセスしてクレジットを購入してください。5 ドルでも数百回の API 呼び出しに十分です。 Code 417 — OAuth 1.0a App Permissions (HTTP 403) X の Access Token に、要求された操作に対する正しい権限がありません。

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

また、x-access-level: read レスポンスヘッダーが表示されることがあり、これは Access Token が読み取り専用権限で生成されたことを示します。 Action: X Developer Console でアプリの権限を Read and write and Direct message に更新し、Keys and tokens で Access Token を再生成してください。新しいトークンは更新された権限を継承します。詳細は X BYO Key Setup Guide をご覧ください。 Code 419 - Missing BYO Credentials (HTTP 400) X/Twitter 操作にはリクエストヘッダーに BYO API 認証情報が必要です。両方のヘッダーが欠落している場合、また片方のみが存在する場合にも Ayrshare はコード 419 を返します。message の文字列は、どのヘッダーが欠落しているかによって変わります。 X-Twitter-OAuth1-Api-Key と X-Twitter-OAuth1-Api-Secret の両方が欠落している場合:

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

片方のみが存在する場合(例: キーはあるがシークレットがない):

{
  "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: X 向けのすべてのリクエストで、X-Twitter-OAuth1-Api-Key と X-Twitter-OAuth1-Api-Secret の両方を送信してください。片方だけを提供した場合、同じコードでリクエストが拒否されます。ヘッダー一覧については X BYO Keys Header Reference をご覧ください。 Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403) X/Twitter リクエストがサポート終了済みのレガシー(非 BYO)OAuth パスに依存している場合に返されます。X API へのアクセスには、リクエストヘッダーで提供される独自の X Developer App の認証情報が必要になりました。

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

Action: X Developer App を構成し、X 向けの各リクエストで X-Twitter-OAuth1-Api-Key と X-Twitter-OAuth1-Api-Secret ヘッダーを送信してください。詳細なセットアップ手順については X BYO Key Setup Guide をご覧ください。

Caption 拡張エラー

Code 441 — Caption Enhancement Failed (HTTP 502) 投稿の準備中に、キャプション拡張(shortenLinks など)が 1 つ以上のプラットフォームで失敗した場合に返されます。影響を受けた各プラットフォームは、source: "handlePostAdditions" と code: 441 を持つ errors 配列に表示されます。一部のプラットフォームのみが失敗した場合、他のプラットフォームは投稿に成功し、その結果は postIds に表示されます。この場合、トップレベルの status は "error" になりますが、postIds は空ではありません — クライアントは status と errors[] を排他的ではなく、補完的なものとして扱う必要があります。

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

すべての プラットフォームで拡張が失敗した場合、レスポンスはトップレベルで code: 441 と HTTP 502 になり、投稿は作成されません。

{
  "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: キャプション拡張の失敗は通常一時的なものです(基となる短縮サービスや拡張サービスがエラーを返した)。

postIds が空でない場合(一部のプラットフォームで投稿が成功)、完全なプラットフォーム集合を再送信しないでください — 成功したプラットフォームで投稿が重複します。代わりに errors[] を調べて失敗したプラットフォームを特定し、それらのプラットフォームのみでリクエストを再試行するか、独自の冪等リトライフローに依存してください。
postIds が空または存在しない場合(スケジュール/投稿時の完全失敗)、完全なリクエストを安全に再試行できます。
失敗が継続する場合は、拡張フラグを外して投稿(例: shortenLinks を削除)するか、サポートにお問い合わせください。

メディア取得 / クローラーアクセスエラー

Code 440 — Social Network Could Not Download Media (HTTP 400) プラットフォームの公開クローラーが指定した mediaUrl をダウンロードできない場合に返されます — 最も一般的な原因は、robots.txt や WAF / ボット対策ルールがクローラー(例: Meta の facebookexternalhit)をブロックしていることです。details 文字列は上流プラットフォームから提供され、多くの場合 Meta/Instagram エラー 2207052 のテキストです。

{
  "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) 上流レスポンスがコード 440 をトリガーするものより明確でない場合の、Instagram メディア取得失敗のフォールバックコードです。details 文字列は通常 "Restricted by robots.txt" や "HTTP error code 403" を含みます。コード 138 はアスペクト比/フォーマットの問題やその他一般的な Instagram エラーにも使用されるため、メディア取得のバリアントは details 文字列で識別できます。

{
  "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 Threads の公開が失敗した場合に返されます。同じ mediaUrl で両方のプラットフォームに公開する際、コード 440 / 138 と同じメディア取得問題が最も一般的な原因です。Threads API は詳細文字列を返さないため、通常は同じ公開処理で Instagram の 440 または 138 が同時発生していないかを確認して診断します。

{
  "status": "error",
  "errors": [{
    "status": "error",
    "code": 379,
    "message": "Error posting to Threads.",
    "action": "post",
    "platform": "threads"
  }],
  "postIds": [],
  "id": "..."
}

Action: robots.txt のスニペットや検証コマンドを含む完全なトラブルシューティングについては、Meta Media Crawler Blocked をご覧ください。

Facebook Analytics のレート制限

Code 444 — Facebook Page Analytics Rate Limit (HTTP 429) Facebook ページが Meta の分析エンドポイントのページごとのレート制限を超えた場合に返されます。基となる Meta エラーは 80001(「There have been too many calls to this Page account.」)です。ページの連携は維持され、公開は引き続き機能します — スロットルされるのはそのページの分析ファンアウトのみです。 /history/facebook または analytics レスポンスの単一投稿でスロットルが検知された場合、影響を受けた各投稿は facebook.code に code: 444 と 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: 数分待ってから再試行してください。Meta のページごとのレート制限ウィンドウは、通常はページ側で何もしなくても 1 時間以内に解消します。ユーザーにアカウントの再連携を促さないでください — これは Meta 側の一時的なスロットルであり、認可の失敗ではありません。

以前この状況を code: 161(「Facebook authorization error … unlink and re-link」)として処理していた場合、code: 444 を認識するように統合を更新し、再連携フローを開始する代わりにバックオフ付きで再試行してください。161 への分類は 2026 年 4 月に修正されました。

Meta の身元確認

Code 326 — Meta Identity Verification Required (HTTP 403) Meta が接続されたアカウントに対して、リクエストを受け入れる前に追加の身元確認を要求している場合に返されます。これは Meta プラットフォーム全体 — Facebook、Instagram、Facebook Groups、Threads、Messenger — に適用されます。アカウントの再接続では 解決しません — 確認は Meta 側で完了する必要があります。

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

Action: アカウント所有者に Meta Business Support で Meta の身元確認を完了してもらい、その後リクエストを再試行してください。ユーザーにアカウントの再連携を促さないでください — 再連携ではこの要件はクリアされません。

Facebook アカウント制限

Code 476 — Facebook Account Restriction (HTTP 400) Meta がアカウントに制限をかけたために Facebook への投稿が失敗した場合に返されます(Meta のエラーサブコード 2424009 および 1404078、またはエラーにサブコードがない場合の Meta の制限文言)。これは一時的な公開の問題ではなく、アカウントレベルの制限です — 再試行不可 で、retryAvailable フラグは 付きません。Meta で制限が解除されるまで、同じ投稿を再送信しても成功しません。アカウントは Ayrshare に連携されたままで、再連携は不要です。 Meta は API 経由で具体的な制限理由を返さないため、顧客は Meta の Account Status ページを直接確認して理由と申し立てを確認する必要があります。Meta が独自の文言を提供する場合、Ayrshare はそれを details フィールドに表示します。Ayrshare は制限を検知した際、アカウント所有者に通知メールも送信します。

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

Action: Facebook にログインし、右上のプロフィール画像をクリックして Help セクションを開き、Account Status を選択してください。そこにある Meta のサポートアシスタントが具体的な制限理由を表示し、申し立てを可能にします。制限は Meta によりアカウントレベルで適用されるため、このコードは再試行不可です — 自動リトライロジックを組まないでください。まず Meta で制限を解決してください。

画像フォーマット変換エラー

Ayrshare は、WebP、HEIC、AVIF 画像を受け付けないプラットフォーム(WebP は Instagram、LinkedIn、TikTok、Google My Business、Threads、Snapchat、HEIC と AVIF はすべてのプラットフォーム)に投稿する前に、これらを自動的に JPEG に変換します。変換は送信時に透過的に実行されます。以下の 3 つのエラーは、変換パイプライン自体が完了できない場合にのみ発生します。ソース画像がサポートされているフォーマットの場合、変換は試行されず、これらのコードは表示されません。 Code 450 — Image Format Conversion Failed (HTTP 400) 画像はダウンロードされましたが、JPEG として再エンコードできませんでした。最も一般的な原因は、ソースファイルの破損、コンテナ内の予期しない内部フォーマット、または変換サイズ上限を超える画像です。

{
  "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: ソース mediaUrl を直接ブラウザで開き、レンダリングされることを確認してください。レンダリングされる場合は、画像をクリーンな JPEG または PNG に再エクスポートしてから投稿を再試行してください。 Code 451 — Image Download Failed for Conversion (HTTP 400) 変換パイプラインがソース画像を取得できませんでした。典型的な原因は、オリジンからの 4xx/5xx レスポンス、ネットワークタイムアウト、ホップ制限を超えるリダイレクトチェーン、または非公開アドレスに解決される URL(SSRF ガードによりブロック)などです。details フィールドが存在する場合、その基になる原因文字列が含まれます。

{
  "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: mediaUrl が公開されており、到達可能であることを確認してください(認証なし、robots.txt ブロックなし、HTTPS で解決)。URL がリダイレクトする場合、最終的な宛先も公開されており、プライベートネットワーク上にないことを確認してください。 Code 452 — Converted Image Upload Failed (HTTP 500) 変換は成功しましたが、変換された JPEG を Ayrshare の一時ストレージバケットにステージングできませんでした。これは Ayrshare 側の内部的な失敗で、再試行可能です。

{
  "status": "error",
  "errors": [
    {
      "action": "image conversion",
      "status": "error",
      "code": 452,
      "message": "An error occurred uploading the converted image. Please try again.",
      "platform": "tiktok"
    }
  ]
}

Action: 投稿を再試行してください。複数回のリトライにもかかわらずエラーが継続する場合は、mediaUrl と概算タイムスタンプをサポートまでお知らせください。

YouTube 一時的アップロードエラー

以下のエラーコードは、通常は一時的で安全に再試行できる YouTube アップロード失敗に対する具体的なシグナルを提供します。両方のレスポンスに retryAvailable: true が含まれているため、統合では HTTP ステータスコードではなくこの真偽値で分岐できます。以前 YouTube アップロード用の code: 176 レスポンスの多くは、現在 453(一時的タイムアウト)または 454(一時的サービス利用不可)にルーティングされ、いずれも retryAvailable: true を持ちます。統合で HTTP 500 をフィルタして YouTube アップロードを再試行している場合、レスポンスボディの retryAvailable フィールドでフィルタするように切り替えてください。 Code 453 — YouTube Upload Timed Out (HTTP 504) Google の YouTube 取り込みパイプラインがアップロード受け入れ中にタイムアウトした場合に返されます。通常は一時的で、1〜2 分以内に自然に解消します。

{
  "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: 指数バックオフで 1〜2 分後に投稿を再試行してください。再試行可能な失敗を検出するには、HTTP ステータスではなくレスポンスボディの retryAvailable フィールドで分岐してください。同じペイロードを再送信するには retry post エンドポイントを使用できます。 Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503) YouTube のアップロードエンドポイントが 5xx ステータスを返した場合、または YouTube への接続がソケット層でリセット/タイムアウトした場合(ECONNRESET、ETIMEDOUT、ESOCKETTIMEDOUT)に返されます。これらの状況は一時的です。

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

Action: 指数バックオフで投稿を再試行してください。再試行可能な失敗を検出するには、HTTP ステータスではなくレスポンスボディの retryAvailable フィールドで分岐してください。同じペイロードを再送信するには retry post エンドポイントを使用できます。

YouTube サムネイルエラー Code 307

カスタム YouTube thumbNail を適用できない場合、コード 307 が返されます。動画自体の投稿が成功した場合、これは投稿を失敗させ ません — YouTube 結果の status は "success" のままで、warnings 配列(feature: "thumbnail"、code: 307)に追加的に失敗が表示されます。後方互換性のためレガシーの thumbnail サブオブジェクトも保持されます。最も一般的な原因は、YouTube チャンネルが未確認 であることです。チャンネルが電話認証を完了していない場合、YouTube は上流の 403 と汎用メッセージ "The authenticated user doesn't have permissions to upload and set custom video thumbnails" を返します。この文言は OAuth の問題のように聞こえますが、実際にはほとんど常に認証の問題であるため、まずチャンネルを確認してください。YouTube アカウントの再連携は二次的な原因です。

{
  "status": "success",
  "id": "<videoId>",
  "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": "<upstream message>"
  },
  "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": "<upstream message>"
    }
  ]
}

Ayrshare は可能な限り、公開前にサムネイルの検証も行います。ファイルは PNG または JPG/JPEG、2MB 以下、到達可能な URL から配信される必要があります。サムネイルの問題で 投稿が失敗することはありません — 動画は常に公開され、失敗は常に致命的でない warnings エントリとして表示されます(トップレベルの status は "success" のまま)。これは問題の検知時期にかかわらず当てはまります。

アップロード前に検知された場合。 公開前の検証でサムネイルが無効(誤ったファイルタイプ、2MB を超えることが確認された、または到達不可の URL)と確実に判定できる場合、Ayrshare はサムネイルをスキップして動画を公開し、正確な理由を warnings に報告します — これにより失敗確実なアップロード試行を回避し、プロバイダーが返すものより明確なメッセージが得られます。
アップロード後に検知された場合。 YouTube がリクエストを処理して初めて検知できる失敗(例: 未確認チャンネルの 403 や、大きすぎる画像の 413)の場合、動画は既に公開されており、失敗は同じ warnings 配列に表示されます。

いずれの場合も、レスポンスはこのセクションの前半で示した status: "success" + warnings の例のようになります。 Action: https://www.youtube.com/verify で YouTube チャンネルを確認(電話認証)してください。チャンネルが既に確認済みでもサムネイルが失敗する場合は、Social Accounts で YouTube アカウントの連携を解除して再連携し、すべての権限を付与してください。完全なトラブルシューティングガイドは YouTube Thumbnail Not Applied (Unverified Channel) をご覧ください。

Reddit 投稿エラー

Code 442 — Reddit Banned Subreddit (HTTP 400) アカウントが対象の subreddit への投稿を禁止されている場合に返されます。再試行不可 です — そのまま再送信しても投稿は成功しません。メッセージには影響を受けた subreddit 名(例: r/news)が含まれます。

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

Action: ターゲット subreddits から禁止されている subreddit を削除してください。投稿を変更せずに再試行しても成功しません。 Code 443 — Reddit Disallowed Word in Title (HTTP 400) タイトルに禁止された単語が含まれているため subreddit が投稿を拒否した場合に返されます。再試行前にタイトルを編集してください — そのまま再送信しても成功しません。メッセージには影響を受けた subreddit 名(例: r/news)が含まれます。

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

Action: 投稿タイトルを編集して禁止された単語を削除し、再試行してください。

モデレーションエラー

Code 438 — Moderation Input Rejected (HTTP 400) POST /validate/moderation で AI プロバイダーが提供された入力を拒否した場合に返されます — 例えばサポートされていないファイルタイプなど。これはリクエストの入力の問題であり、一時的な処理失敗ではありません。

{
  "status": "error",
  "errors": [
    {
      "action": "moderation",
      "status": "error",
      "code": 438,
      "message": "There was an issue with the AI processing."
    }
  ]
}

Action: モデレーション入力が有効で、サポートされているファイルタイプを使用していることを確認し、再送信してください。

コード 438 と コード 331 を対比してください。コード 331 は同じモデレーションシナリオをカバーしますが、プロバイダー側の真の処理失敗を表します(HTTP 500、メッセージ「There was an issue with the AI processing. Please try again.」)。コード 331 は一時的なサーバー側の失敗で再試行可能ですが、コード 438 は入力自体が拒否されたことを示すため、再試行前に修正する必要があります。

LinkedIn Analytics エラー

Code 475 — Re-link LinkedIn Profile for Analytics (HTTP 403) メンバー分析が出荷される前に連携された個人(メンバー)LinkedIn プロファイルに対して、POST /analytics/post および POST /analytics/social で返されます。これらのプロファイルには LinkedIn メンバー分析スコープ(r_member_postAnalytics、r_member_profileAnalytics)が欠落しているため、LinkedIn は分析リクエストを拒否します。投稿は影響を受けません。

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

Action: アカウント所有者に Social Accounts で LinkedIn プロファイルを再連携して新しい分析スコープを付与してもらい、分析リクエストを再試行してください。再連携後、エラーがクリアされるまで数分お待ちください: Ayrshare はこのエラーを短時間キャッシュし、LinkedIn もトークンの権限をキャッシュするため、再連携済みプロファイルでも分析が成功するまで最大 5〜10 分間ほどコード 475 を返し続けることがあります。

TikTok コメントエラー

Code 288 — TikTok Comment Deferred / Post Still Processing (HTTP 400) TikTok は動画を非同期に処理するため、公開されたばかりの投稿の id は、TikTok の post.publish.publicly_available Webhook が実際の動画 ID を解決するまで "pending" となります。まだ処理中の投稿(または id が "failed" の投稿)に対する get-comments、comment、reply リクエストは、TikTok への呼び出しの前に拒否され、汎用の失敗ではなくコード 288 を返します。

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

Action: TikTok の処理完了を待ってから再試行してください。tikTokPublished Scheduled Action Webhook をリッスンするか、/history をポーリングして、投稿 id が解決された数値の動画 ID になるまで待機します。first comment は投稿が解決されると自動的に投稿されるため、再試行する必要はありません。"failed" の投稿の場合、メッセージは代わりに動画の公開が失敗し、アクションは実行されないことを示します。

エラーメッセージの翻訳

API エラーメッセージのレスポンスは、指定した言語に自動的に翻訳できます。これは、ユーザーの希望する言語でエラーを直接表示したい場合に便利です。ソーシャル連携ページの言語を選択したい場合は、こちらをご覧ください。ヘッダーに次を含めます:

"Translate-Error-Message": "Language_Code"

ここで Language_Code は、利用可能な言語コードのいずれかです。例えば、次はエラーをフランス語に翻訳します。

"Translate-Error-Message": "fr" // Translate to French

当社のシステムは、エラーメッセージの言語を自動的に検出します。

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

エラーのハンドリング

Instagram 固有のエラーコード

Retry Available

X/Twitter BYO Key エラー

Caption 拡張エラー

メディア取得 / クローラーアクセスエラー

Facebook Analytics のレート制限

Meta の身元確認

Facebook アカウント制限

画像フォーマット変換エラー

YouTube 一時的アップロードエラー

YouTube サムネイルエラー Code 307

Reddit 投稿エラー

モデレーションエラー

LinkedIn Analytics エラー

TikTok コメントエラー

エラーメッセージの翻訳

​エラーのハンドリング

​Instagram 固有のエラーコード

​Retry Available

​X/Twitter BYO Key エラー

​Caption 拡張エラー

​メディア取得 / クローラーアクセスエラー

​Facebook Analytics のレート制限

​Meta の身元確認

​Facebook アカウント制限

​画像フォーマット変換エラー

​YouTube 一時的アップロードエラー

​YouTube サムネイルエラー Code 307

​Reddit 投稿エラー

​モデレーションエラー

​LinkedIn Analytics エラー

​TikTok コメントエラー

​エラーメッセージの翻訳

エラーのハンドリング

Instagram 固有のエラーコード

Retry Available

X/Twitter BYO Key エラー

Caption 拡張エラー

メディア取得 / クローラーアクセスエラー

Facebook Analytics のレート制限

Meta の身元確認

Facebook アカウント制限

画像フォーマット変換エラー

YouTube 一時的アップロードエラー

YouTube サムネイルエラー Code 307

Reddit 投稿エラー

モデレーションエラー

LinkedIn Analytics エラー

TikTok コメントエラー

エラーメッセージの翻訳