> ## Documentation Index
> Fetch the complete documentation index at: https://ayrshare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ayrshare Error Codes

> Ayrshare 固有の返却エラーコード。

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

<Info>
  エラーは 400、401、402、403、404、429、500、502、503、または 504 のステータスコードを返します。成功はステータスコード 200 を返します。詳細は [こちら](/errors/errors-http) をご覧ください。
</Info>

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

例えば、Twitter と Facebook で重複と判定された投稿は、次のようなレスポンスを返します。

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

注意事項:

<ul class="custom-bullets">
  <li>
    `errors` フィールドには、エラーが発生した各ソーシャルネットワークごとに 1 つのエラーを持つ配列が含まれます。
  </li>

  <li>`action` は返されたエラーの種類を示します。</li>

  <li>
    API 呼び出しが失敗した場合、トップレベルの `status` フィールドは "error" になります。例えば /post 呼び出しで、すべてのソーシャルネットワークへの投稿が成功すれば `status` フィールドは "success"、そうでなければ status フィールドは "error" になります。
  </li>

  <li>`code` フィールドには Ayrshare のリファレンスエラーコードが含まれます。</li>
  <li>`message` フィールドはエラーの具体的な詳細です。</li>
</ul>

### エラーのハンドリング

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

<ul class="custom-bullets">
  <li>レスポンスのリターンコードが `200` ではない</li>
  <li>JSON レスポンスの status が `error`</li>
</ul>

例えば、ユーザーが Facebook の連携を解除した場合(パスワードを変更した、Ayrshare のアクセスを削除した)、投稿時に次のレスポンスと `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"
}
```

アクションとしては、ダッシュボード、テキスト、またはメールでユーザーに通知することが挙げられます。

もう 1 つの例として、投稿した Instagram の画像の寸法や比率が不正な場合、`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?"
}
```

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

### Instagram 固有のエラーコード

以下のエラーコードは、Instagram 投稿失敗に関する具体的な詳細を提供し、可能な場合は汎用エラー 138 を置き換えます。

**Code 435 — Instagram Rate Limit (HTTP 429)**

Instagram のプロフェッショナル(Business / Creator)アカウントは、Meta の [Content Publishing API](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user/content_publishing_limit/) 上で、24 時間のローリングで 50 件までの投稿制限があります(個人アカウントは API 経由で公開できないため、この制限に達することはありません)。制限を超えると Meta はレート制限エラーを返します。Ayrshare は、Meta の公開エンドポイントが直接 HTTP 429 を返した場合、または内部エラーサブコード(`1390008`)が投稿/コメントのスロットルを示す場合にも `code: 435` を表示します。

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

**Action:** 再試行前にレート制限ウィンドウがリセットされるまでお待ちください。Meta が `Retry-After` ヘッダーを提供する場合、その値(秒)は `details` フィールドに含まれます — 少なくともその時間だけ待ってから再送信してください。

**Code 436 — Instagram Media Processing Timeout (HTTP 400)**

Instagram のアップロード済みメディアの処理に時間がかかりすぎました。これは大きな動画ファイルの場合、または Meta のサーバー負荷が高い時間帯に発生することがあります。

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

**Action:** [retry post](/apis/post/retry-post) エンドポイントを使用して投稿を再試行してください。問題が継続する場合は、メディアファイルのサイズを縮小してみてください。

**Code 447 — Instagram Trial Reels: Missing graduationStrategy (HTTP 400)**

[`/post`](/apis/post/post) リクエストで `instagramOptions.trialParams` が指定されているが、`graduationStrategy` が欠落、`null`、または空文字列の場合に返されます。トライアル Reels には明示的な graduation ストラテジーが必要です — [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"
    }
  ]
}
```

**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 文字に切り詰め)がエコーされます。

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

**Action:** `graduationStrategy` を厳密に `"MANUAL"` または `"SS_PERFORMANCE"`(大文字、文字列型)として送信してください。

**Code 449 — Instagram Trial Reels: Incompatible Media (HTTP 400)**

メディアまたは投稿の形式がトライアル Reel の対象外の場合に返されます。トライアル Reels は単一の `.mp4` または `.mov` 動画である必要があります — カルーセル(URL が複数)、ストーリー(`instagramOptions.stories: true`)、動画以外の拡張子はすべて拒否されます。`details` フィールドで、どのサブケースが発生したかを判別できます。

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

**Action:** `stories: true` フラグを付けずに、単一の `.mp4` または `.mov` 動画 URL を送信してください。追加の `mediaUrls` エントリを削除するか、通常のカルーセル/ストーリー投稿を意図していた場合は `trialParams` を削除してください。

**Code 258 — Instagram Account-State Error (HTTP 400)**

基本メッセージ「Error with Instagram.」を持つ、Instagram アカウント状態に関する一般的な失敗。投稿の内容ではなく、接続された Instagram アカウントの状態が原因で Meta がリクエストを拒否した場合に表示されます。

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

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

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

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

#### Retry Available

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

```json theme={"system"}
{
  "retryAvailable": true
}
```

その後、同じペイロードで呼び出しを再試行できます。
投稿の場合は、[retry post](/apis/post/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](https://x.com) にログインし、どのケースに該当するかを確認してください。

投稿パスは最小限のレスポンスを返します。

```json theme={"system"}
{
  "status": "error",
  "code": 272,
  "message": "Failed to verify BYO Twitter identity",
  "platform": "twitter"
}
```

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

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

`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 呼び出しにはクレジットが必要です。

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

**Action:** [console.x.com](https://console.x.com) → Billing → Credits にアクセスしてクレジットを購入してください。5 ドルでも数百回の API 呼び出しに十分です。

**Code 417 — OAuth 1.0a App Permissions (HTTP 403)**

X の Access Token に、要求された操作に対する正しい権限がありません。

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

また、`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](/dashboard/connect-social-accounts/x-twitter-byo-keys#troubleshooting) をご覧ください。

**Code 419 - Missing BYO Credentials (HTTP 400)**

X/Twitter 操作にはリクエストヘッダーに BYO API 認証情報が必要です。両方のヘッダーが欠落している場合、また片方のみが存在する場合にも Ayrshare はコード 419 を返します。`message` の文字列は、どのヘッダーが欠落しているかによって変わります。

`X-Twitter-OAuth1-Api-Key` と `X-Twitter-OAuth1-Api-Secret` の両方が欠落している場合:

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

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

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

**Action:** X 向けのすべてのリクエストで、`X-Twitter-OAuth1-Api-Key` と `X-Twitter-OAuth1-Api-Secret` の両方を送信してください。片方だけを提供した場合、同じコードでリクエストが拒否されます。ヘッダー一覧については [X BYO Keys Header Reference](/dashboard/connect-social-accounts/x-twitter-byo-keys#header-reference) をご覧ください。

**Code 423 — Legacy X/Twitter OAuth No Longer Supported (HTTP 403)**

X/Twitter リクエストがサポート終了済みのレガシー(非 BYO)OAuth パスに依存している場合に返されます。X API へのアクセスには、リクエストヘッダーで提供される独自の X Developer App の認証情報が必要になりました。

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

**Action:** X Developer App を構成し、X 向けの各リクエストで `X-Twitter-OAuth1-Api-Key` と `X-Twitter-OAuth1-Api-Secret` ヘッダーを送信してください。詳細なセットアップ手順については [X BYO Key Setup Guide](/dashboard/connect-social-accounts/x-twitter-byo-keys) をご覧ください。

### Caption 拡張エラー

**Code 441 — Caption Enhancement Failed (HTTP 502)**

投稿の準備中に、キャプション拡張([`shortenLinks`](/apis/post/post) など)が 1 つ以上のプラットフォームで失敗した場合に返されます。影響を受けた各プラットフォームは、`source: "handlePostAdditions"` と `code: 441` を持つ `errors` 配列に表示されます。

一部のプラットフォームのみが失敗した場合、他のプラットフォームは投稿に成功し、その結果は `postIds` に表示されます。この場合、トップレベルの `status` は `"error"` になりますが、`postIds` は空ではありません — クライアントは `status` と `errors[]` を排他的ではなく、補完的なものとして扱う必要があります。

```json theme={"system"}
{
  "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` になり、投稿は作成されません。

```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. <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 のテキストです。

```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)**

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

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

```json theme={"system"}
{
  "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](/help-center/technical-support/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`](/apis/history/history-platform) または [analytics](/apis/analytics/social) レスポンスの単一投稿でスロットルが検知された場合、影響を受けた各投稿は `facebook.code` に `code: 444` と `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": "..."
}
```

**Action:** 数分待ってから再試行してください。Meta のページごとのレート制限ウィンドウは、通常はページ側で何もしなくても 1 時間以内に解消します。ユーザーにアカウントの再連携を促さ **ない** でください — これは Meta 側の一時的なスロットルであり、認可の失敗ではありません。

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

### Meta の身元確認

**Code 326 — Meta Identity Verification Required (HTTP 403)**

Meta が接続されたアカウントに対して、リクエストを受け入れる前に追加の身元確認を要求している場合に返されます。これは Meta プラットフォーム全体 — Facebook、Instagram、Facebook Groups、Threads、Messenger — に適用されます。アカウントの再接続では **解決しません** — 確認は 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"
    }
  ]
}
```

**Action:** アカウント所有者に [Meta Business Support](https://www.facebook.com/business-support-home) で 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 は制限を検知した際、アカウント所有者に通知メールも送信します。

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

**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 として再エンコードできませんでした。最も一般的な原因は、ソースファイルの破損、コンテナ内の予期しない内部フォーマット、または変換サイズ上限を超える画像です。

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

**Action:** ソース `mediaUrl` を直接ブラウザで開き、レンダリングされることを確認してください。レンダリングされる場合は、画像をクリーンな JPEG または PNG に再エクスポートしてから投稿を再試行してください。

**Code 451 — Image Download Failed for Conversion (HTTP 400)**

変換パイプラインがソース画像を取得できませんでした。典型的な原因は、オリジンからの 4xx/5xx レスポンス、ネットワークタイムアウト、ホップ制限を超えるリダイレクトチェーン、または非公開アドレスに解決される URL(SSRF ガードによりブロック)などです。`details` フィールドが存在する場合、その基になる原因文字列が含まれます。

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

**Action:** `mediaUrl` が公開されており、到達可能であることを確認してください(認証なし、`robots.txt` ブロックなし、HTTPS で解決)。URL がリダイレクトする場合、最終的な宛先も公開されており、プライベートネットワーク上にないことを確認してください。

**Code 452 — Converted Image Upload Failed (HTTP 500)**

変換は成功しましたが、変換された JPEG を Ayrshare の一時ストレージバケットにステージングできませんでした。これは Ayrshare 側の内部的な失敗で、再試行可能です。

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

**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 分以内に自然に解消します。

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

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

**Code 454 — YouTube Upload Service Temporarily Unavailable (HTTP 503)**

YouTube のアップロードエンドポイントが 5xx ステータスを返した場合、または YouTube への接続がソケット層でリセット/タイムアウトした場合(`ECONNRESET`、`ETIMEDOUT`、`ESOCKETTIMEDOUT`)に返されます。これらの状況は一時的です。

```json theme={"system"}
{
  "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](/apis/post/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 アカウントの再連携は二次的な原因です。

```json theme={"system"}
{
  "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](https://www.youtube.com/verify) で YouTube チャンネルを確認(電話認証)してください。チャンネルが既に確認済みでもサムネイルが失敗する場合は、[Social Accounts](https://app.ayrshare.com/social-accounts) で YouTube アカウントの連携を解除して再連携し、すべての権限を付与してください。完全なトラブルシューティングガイドは [YouTube Thumbnail Not Applied (Unverified Channel)](/help-center/technical-support/youtube_thumbnail_unverified_channel) をご覧ください。

### Reddit 投稿エラー

**Code 442 — Reddit Banned Subreddit (HTTP 400)**

アカウントが対象の subreddit への投稿を禁止されている場合に返されます。**再試行不可** です — そのまま再送信しても投稿は成功しません。メッセージには影響を受けた subreddit 名(例: `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"
    }
  ]
}
```

**Action:** ターゲット subreddits から禁止されている subreddit を削除してください。投稿を変更せずに再試行しても成功しません。

**Code 443 — Reddit Disallowed Word in Title (HTTP 400)**

タイトルに禁止された単語が含まれているため subreddit が投稿を拒否した場合に返されます。再試行前にタイトルを編集してください — そのまま再送信しても成功しません。メッセージには影響を受けた subreddit 名(例: `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"
    }
  ]
}
```

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

### モデレーションエラー

**Code 438 — Moderation Input Rejected (HTTP 400)**

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

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

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

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

### LinkedIn Analytics エラー

**Code 475 — Re-link LinkedIn Profile for Analytics (HTTP 403)**

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

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

**Action:** アカウント所有者に [Social Accounts](https://app.ayrshare.com/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](/apis/comments/get-comments)、comment、reply リクエストは、TikTok への呼び出しの前に拒否され、汎用の失敗ではなくコード 288 を返します。

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

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

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

API エラーメッセージのレスポンスは、指定した言語に自動的に翻訳できます。
これは、ユーザーの希望する言語でエラーを直接表示したい場合に便利です。

[ソーシャル連携ページの言語を選択](/multiple-users/manage-user-profiles#set-language-for-the-social-linking-page) したい場合は、こちらをご覧ください。

ヘッダーに次を含めます:

```json theme={"system"}
"Translate-Error-Message": "Language_Code"
```

ここで `Language_Code` は、利用可能な[言語コード](/iso-codes/language) のいずれかです。

例えば、次はエラーをフランス語に翻訳します。

```json theme={"system"}
"Translate-Error-Message": "fr" // Translate to French
```

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