エラー

すべてのエラーは、HTTP ステータスと同じ JSON エンベロープで返されます。code がコードで読み取る契約であり、message は人間向けで、変更されることがあります。

json

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

details には、拒否されたフィールド、ネットワークの理由、使い切ったレート制限のウィンドウなどの詳細が入ります。
docUrl は、このページにあるコードの説明へのリンクです。
requestId はリクエストを識別します。サポートに問い合わせる際にお伝えください。

OAuth エンドポイント（/v1/oauth/token、/v1/oauth/authorize）は、RFC 6749 の形式で応答します：{ "error": "invalid_grant", "error_description": "…" }。

エラーコード

ステータス	コード	意味
400	`invalid_request`	ボディ、クエリ、またはパラメータが無効です。拒否されたフィールドごとに 1 件の詳細（`field`、`code`（`required`、`is_string`、`max` など）、`message`）が付きます。
400	`invalid_json`	ボディが有効な JSON ではありません。
400	`invalid_cursor`	このカーソルは Sofia API が返したものではありません。
400	`webhook_url_invalid`	webhook のアドレスが https ではないか、プライベートアドレスを指しています。
400	`webhook_event_invalid`	不明な webhook イベントです。
400	`application_name_invalid`	設定 › API: クライアント名がない、または長すぎます。
400	`application_profile_invalid`	設定 › API: クライアントのプロフィールに無効な項目があります。詳細にその項目名が示されます。
400	`logo_invalid`	設定 › API: ロゴが拒否されました(180×180 px 以上、PNG、JPEG または WebP、2 MB 以下)。
401	`invalid_token`	トークンがない、不明、期限切れ、または取り消されています。あるいは、トークンの持ち主が、トークンに付与された権限を失っています。`WWW-Authenticate` ヘッダーを参照してください。
401	`unauthorized`	認証が必要です。
402	`subscription_required`	live の書き込み（ドライランを含む）には、有効なサブスクリプションまたはトライアルが必要です。
403	`insufficient_scope`	トークンにエンドポイントのスコープがありません。詳細に該当のスコープが示されます。
403	`insufficient_role`	この Workspace でのあなたのロールでは、この操作は許可されていません。
403	`live_mode_required`	テストトークンでの実際の書き込みです。
403	`route_closed_to_applications`	このエンドポイントはアプリケーションには公開されていません。
403	`forbidden`	アクセスが拒否されました。
403	`session_required`	設定 › API: この操作にはトークンではなく Sofia のセッションが必要です。
403	`impersonation_forbidden`	設定 › API: この操作は借用したセッションでは拒否されます。
403	`workspace_owner_required`	この操作は Workspace のオーナーだけが行えます。
403	`workspace_member_required`	あなたはこの Workspace のメンバーではありません。
404	`route_not_found`	このメソッドとパスに応答するエンドポイントはありません。
404	`establishment_not_found`	不明な店舗、またはトークンの範囲外です。
404	`media_not_found`	不明なメディア、またはトークンの範囲外です。
404	`post_not_found`	不明な投稿、またはトークンの範囲外です。
404	`webhook_not_found`	不明な webhook、または別のアプリケーションのものです。
404	`not_found`	リソースが存在しません。
404	`application_not_found`	設定 › API: 不明なクライアントです。
404	`grant_not_found`	不明な認可、またはすでに取り消されています。
404	`personal_key_not_found`	設定 › API: 不明な個人キーです。
404	`consent_not_found`	認可リクエストの期限が切れたか、存在しません。認可エンドポイントからやり直してください。
405	`method_not_allowed`	このエンドポイントでは、このメソッドは許可されていません。
409	`post_in_flight`	ネットワークが投稿を送信中です。少し待ってから削除を再試行してください。
409	`post_not_editable`	ネットワークがすでに投稿を送信したため、編集できません。
409	`account_already_connected`	このネットワークはすでに店舗に連携されています。
409	`webhook_limit_reached`	アプリケーションの webhook がすでに 10 件に達しています。
409	`idempotency_in_progress`	この `Idempotency-Key` での最初のリクエストがまだ実行中です。
409	`conflict`	リクエストがリソースの現在の状態と競合しています。
409	`scope_removal_forbidden`	設定 › API: クライアントの権限は追加できますが、削除はできません。
409	`public_client_has_no_secret`	設定 › API: パブリッククライアントにはシークレットがありません。
413	`payload_too_large`	ファイルがアップロードの上限を超えています。
415	`unsupported_media_type`	サポートされていないコンテンツタイプです。
422	`post_refused`	ネットワーク、店舗、またはご利用のプランが投稿を拒否します。理由ごとに 1 件の詳細があり、それぞれに `message` が付きます。
422	`media_import_refused`	この URL からメディアをインポートできませんでした。理由は詳細に記載されます。
422	`media_upload_refused`	アップロードされたファイルは、サポートされている画像または動画ではありません。
422	`platform_not_offered`	このネットワークは連携の対象外です。
422	`idempotency_key_reused`	この `Idempotency-Key` は別のボディで使用されました。
422	`unprocessable_entity`	リクエストは理解されましたが、処理できません。
429	`rate_limit_exceeded`	レート制限のウィンドウが上限に達しました。`Retry-After` の時間だけ待ってください。

投稿が拒否される理由

post_refused は、各理由を details[].code に一覧します。

コード	意味
`unsupported_platform`	このネットワークはサポートされていません。
`duplicate_platform`	同じネットワークが 2 回指定されています。
`unsupported_format`	このネットワークはこのフォーマットに対応していません。
`caption_too_long`	テキストが長すぎます（`max`、`actual`）。
`too_many_hashtags`	ハッシュタグが多すぎます（`max`、`actual`）。
`too_many_mentions`	メンションが多すぎます（`max`、`actual`）。
`too_many_thread_posts`	スレッドが長すぎます（`max`、`actual`）。
`too_many_media`	メディアが多すぎます（`max`、`actual`）。
`media_mix_refused`	このネットワークでは、写真と動画を混在させることはできません。
`media_required`	このネットワークには写真または動画が必要です。
`media_type_refused`	このネットワークは、この種類のメディアを受け付けません。
`scheduled_in_past`	`scheduledAt` が過去の日時です。
`scheduled_at_invalid`	予約投稿には、未来の `scheduledAt` が必要です。
`account_not_connected`	この店舗には、このネットワークに連携されたアカウントがありません。
`account_ambiguous`	このネットワークには複数のアカウントが連携されています。`accountId` で 1 つ指定してください。
`media_not_found`	このメディアは、この店舗のライブラリにありません。
`media_url_invalid`	メディアの URL は、公開された https のアドレスである必要があります。
`platform_unavailable`	このネットワークは、まだ Sofia では利用できません。
`publication_quota_exceeded`	ご利用のプランの投稿数の上限に達しました。

エラーの扱い方

message ではなく、必ず code で分岐してください。
429 は Retry-After の後に、5xx は指数バックオフで再試行してください。
4xx は、そのままでは再試行しないでください。先にリクエストを修正します。
失敗のたびに requestId をログに残してください。