エラーコードとレスポンス

​

一般的なレスポンス構造

成功したレスポンスは、200 番台の HTTP コードと、要求されたオブジェクトが返却／作成／変更／削除されたことに加えて、サーバーがリクエストをどのように解釈したかを表現する JSON ベースのペイロードによって示されます。

成功したリクエストを送信した場合、レスポンスには、リクエスト内容をそのまま返す request ノードが含まれます。

例: GET accounts/abcdefg/campaigns?with_deleted=true

{
  /* レスポンスのデータ... */,
  "request": {
    "params": {
      "account_id": "abcdefg",
      "with_deleted": "true"
    }
  }
}

JSON レスポンス内の data フィールドには、対象リソースに紐づく特定のオブジェクトが含まれます。レスポンスに 1 件以上の結果が含まれる可能性がある場合、data ノードの形式は JSON 配列になります。レスポンスとして 1 件の結果しか返らない場合は、JSON ハッシュ (オブジェクト) として返されます。ごくまれに、通常であればコレクション (配列) が含まれるレスポンスで、代わりにハッシュマップが返されることがあります。この場合、その単一のハッシュマップは、type フィールドで指定されているものと同じ type のオブジェクトであるとみなしてください。

​

エラー応答の構造

エラー応答は 200 番台以外の HTTP ステータスコードで返されます。通常は JSON 応答が返されますが、中には異なる形式のボディで返されるエラーもあります。応答構造をパースできない状況では、HTTP ステータスコード本来の意味を優先して解釈してください。たとえば、HTTP 404 とともに HTML 応答が返される場合があります。このときは、そのコンテンツが見つからないと判断して問題ありません (HTTP 404 は「Not Found」を意味します) 。

一般的なエラー応答は、成功時の応答と同様の構造になります。エラーの内容は、応答の errors ノードで示されます。errors/code ノードには、プログラムから解決方法の判断に利用できる CAPS_CASE の定数エラーコードが示されます。errors/message ノードには、そのエラーの (通常は) 人間が読める英語での説明が含まれます。さらに詳細なエラー内容を示すために、追加のフィールドが付与される場合もあります。

{
  "errors": [
    {
      "parameter": "start_time",
      "details": "invalid date",
      "code": "INVALID_PARAMETER",
      "value": "",
      "message": "Expected time, got \"\" for start_time"
    }
  ],
  "request": {
    "params": {
      "account_id": "hkk5"
    }
  }
}

上記の例では、start_time パラメータに無効な値を指定して analytics エンドポイントへリクエストを送信しています。無効なパラメータを含むリクエストでは、errors/code は INVALID_PARAMETER に設定されます。

HTTPコード	エラーコード
403	ACCOUNT_LOCKED_OUT
404	ACCOUNT_MEDIA_NOT_FOUND
403	ACCOUNT_NOT_FOUND
403	ACTION_NOT_ALLOWED
404	APP_EVENT_PROVIDER_CONFIGURATION_NOT_FOUND
404	APP_EVENT_TAG_NOT_FOUND
404	BEHAVIOR_OR_BEHAVIOR_EXPANDED_NOT_FOUND
404	CAMPAIGN_NOT_FOUND
408	CANCELLED_REQUEST
404	CARD_NOT_FOUND
403	CURRENT_USER_SUSPENDED
400	DUPLICATE_TWEET
400	EXCLUSIVE_PARAMETERS
400	FEATURE_NOT_AVAILABLE
403	FUNDING_INSTRUMENT_ACCESS_NOT_ALLOWED
403	FUNDING_INSTRUMENT_EXCEEDS_AVAILABLE_CREDIT_LIMIT
404	FUNDING_INSTRUMENT_NOT_FOUND
403	GENERIC_TWEET_ERROR
400	ILLEGAL_CHARACTERS
400	INCLUSIVE_PARAMETERS
500	INTERNAL_ERROR
404	INVALID_APP_ID
404	INVALID_APP_STORE
400	INVALID_DENOMINATION
400	INVALID_FUNDING_INSTRUMENT
404	INVALID_IAB_CATEGORY
404	INVALID_ID_ILLEGAL_CHARACTERS
400	INVALID_IMAGE
400	INVALID_MEDIA
400	INVALID_MEDIA_ID
400	INVALID_PARAMETER
400	INVALID_PLACEMENT_TYPE
400	INVALID_TAILORED_AUDIENCE_TYPE
400	INVALID_TARGETING_TYPE
400	INVALID_TIME_WINDOW
400	INVALID_TV_SHOW_LOCATIONS
400	INVALID_TWEET
400	INVALID_USER
400	INVALID_USER_ID
423	LOCK_ACQUISITION_TIMEOUT
404	LINE_ITEM_APP_NOT_FOUND
404	LINE_ITEM_NOT_FOUND
404	MACT_APP_NOT_FOUND
403	MALWARE_STATUS
404	MEDIA_CREATIVE_NOT_FOUND
404	MEDIA_NOT_FOUND
405	METHOD_NOT_ALLOWED
400	MISSING_PARAMETER
404	NO_PROVIDER_AVAILABLE_FOR_THIS_CLIENT_APPLICATION
404	NOT_FOUND
404	PROMOTABLE_USER_NOT_FOUND
404	PROMOTED_ACCOUNT_NOT_FOUND
404	PROMOTED_TWEET_NOT_FOUND
403	READONLY_CLIENT_APPLICATION
400	REQUEST_TOO_COMPLEX
404	ROUTE_NOT_FOUND
503	SERVICE_UNAVAILABLE
503	OVER_CAPACITY
400	SPEND_EXCEEDS_BUDGET
404	TAILORED_AUDIENCE_CHANGE_FILE_NOT_FOUND
404	TAILORED_AUDIENCE_NOT_FOUND
404	TAILORED_AUDIENCE_OR_TAILORED_AUDIENCE_EXPANDED_NOT_FOUND
404	TARGETING_CRITERION_NOT_FOUND
400	TOO_MANY_CAMPAIGNS
400	TOO_MANY_LINE_ITEMS
429	TOO_MANY_REQUESTS
400	TV_SHOW_OUTSIDE_MARKET
400	TWEET_CANNOT_BE_BLANK
403	TWEET_IS_SPAM
404	TWEET_NOT_FOUND
429	TWEET_RATE_LIMIT_EXCEEDED
401	UNAUTHORIZED_ACCESS
403	UNAUTHORIZED_CLIENT_APPLICATION
400	UNKNOWN_CARD_TYPE
400	UNKNOWN_CRITERIA_TYPE
403	USER_NOT_FOUND
404	WEB_EVENT_TAG_NOT_FOUND