Error Codes & Responses

Typical Response Structure

Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.

If you had issued a successful request you would receive as part of your response a request node echoing back your request.

Example: GET /2/accounts/abcdefg/campaigns?with_deleted=true

{
  /* the data of your response... */,
  "request": {
    "params": {
      "account_id": "abcdefg",
      "with_deleted": "true"
    }
  }
}

The data field in JSON responses will contain the specific objects associated with the leveraged resource. The format of the data node will be a JSON array when the response may contain one or more results. It will be returned as JSON hash when only one result is possible in response. In some rare cases, you may see a response that would typically include a collection with a hashmap instead. In this case, assume the single hashmap is an object of the same type as specified in the type field.

Error Response Structure

Error responses are served with a non-200-series HTTP code. Usually a JSON response will be attached, but some errors will respond with different kinds of body. In these circumstances where a response structure cannot be parsed, consider the HTTP code’s core meaning to take precedence. For instance, you may occasionally see a HTTP 404 along with a HTML response. In this case, it’s safe to assume that the content cannot be found (HTTP 404 means “Not Found”).

Typical error responses follow a similar structure to successful responses. The nature of the error will be communicated in an errors node of the response. The errors/code node will indicate a CAPS_CASE constant error code you can programmatically consume to make resolution decisions from. The errors/message node will indicate a (usually) human-readable description of the error in English. Additional fields may be attached to indicate finer-grained detail about the error.

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

In the above example, a request to an analytics endpoint was made with an invalid value for the start_time parameter. The errors/code for requests with invalid parameters is INVALID_PARAMETER.

HTTP Code Error Code
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
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