Introduction

The responses from the Advertising APIs contain both an HTTP status code and a response status bundle with the following three items:

A CityGrid status code
The name of the field to which the status message applies, if any
An explanatory status message

Developers should always examine the CityGrid status code; the associated message is provided only as a convenience. Developers may prefer to produce a custom or localized error message from the status code and field in cases where a message needs to be displayed to an end user.

List of Response Codes

The various status codes are shown in alphabetical order in the table below, together with the associated HTTP status and sample message. The messages shown are examples only.

HTTP Status	CityGrid Status Codes	Sample Message
200	ACCOUNT_DELINQUENT	The account is delinquent.
200	ACCOUNT_INACTIVE	The account is inactive.
400	ACCOUNT_NOT_FOUND	No account found for the given username and password.
200	ASSOCIATION_EXISTS	The AdGroup and AdGroupGeo association already exists.
400	AUTH_TOKEN_EXPIRED	The Authentication Token has expired.
400	AUTH_TOKEN_INVALID	The Authentication Token is not valid.
401	AUTH_TOKEN_NONE	No Authentication Token supplied.
405	BAD_REQUEST_TYPE	The request method was not understood. The only request methods accepted are GET and POST.
200	DATA_NOT_FOUND	There is no data for the campaign.
200	DATE_BEFORE_DATE	The end date cannot be before the start date.
200	DUPLICATE	This is a duplicate request, action, or entity for a campaign.
200	ENTITY_ALREADY_IN_USE	The email is already in use.
200	ENTITY_EXISTS	The campaign already exists.
200	ENTITY_EXPIRED	The offer has expired.
200	ENTITY_INACTIVE	The AdGroupAd is not active.
200	ENTITY_LIMIT	The maximum limit for Geo Type has been reached.
200	ENTITY_MISSING_DATA	The campaign is missing a billing day.
200	ENTITY_NOT_ELIGIBLE	The campaign is not eligible for this promotion.
200	ENTITY_NOT_FOUND	The campaign could not be found.
200	ENTITY_NOT_MODIFIED	The end date cannot be modified when the campaign is in an active state.
200	ENTITY_STATE_INVALID	The request could not be processed because place ID is still in a pending state.
400	HEADER_ACCEPT_INVALID	The value of the accept header is invalid.
400	HEADER_ACCEPT_IS_REQUIRED	An accept header is required.
406	HEADER_CONTENT_TYPE_INVALID	The value of the content type header is invalid.
400	HEADER_CONTENT_TYPE_IS_REQUIRED	A content type header is required.
400	INVALID_REQUEST_BODY	The request is malformed or invalid.
200	MONTHLY_BUDGET_REACHED	The monthly budget has been reached.
200	MOP_EXPIRED	The Method of Payment has expired.
200	MOP_INVALID	The Method of Payment is invalid.
200	NO_ASSOCIATION_EXISTS	The AdGroup to AdGroupGeo association does not exist.
403	NO_PERMISSIONS	The referenced entity does not belong to the current account.
400	OPERATOR_INVALID	The operator SET is not supported for this API or action.
400	PARAMETER_CANNOT_BE_ZERO	The parameter budget must have a value of greater than 0. The minimum value should be 1.00.
400	PARAMETER_FORMAT	The parameter budget is formatted incorrectly. Valid format is a number.
400	PARAMETER_INVALID	The parameter AdGroupGeoType was invalid. Valid options are PRIMARY and SECONDARY.
400	PARAMETER_NOT_SUPPORTED	The parameter customerId is not supported.
400	PARAMETER_ONLY_ONE	There can only be one geography type parameter (CityTarget, MetroTarget, ProvinceTarget, Neighborhood) specified.
400	PARAMETER_RANGE_TOO_HIGH	The start date is above the maximum required range. Valid ranges have a maximum of 1 month.
400	PARAMETER_RANGE_TOO_LOW	The start date is below the minimum required range. Valid ranges have a minimum of today.
400	PARAMETER_REQUIRED	The parameter campaign ID is required.
400	PARAMETER_REQUIRED_CONDITIONAL	The business phone is required when the customer is a budget provider.
400	PARAMETER_SIZE_LIMIT_EXCEEDED	The tagline exceeds the size limit of 140.
400	USERNAME_IS_REQUIRED	A username is required.
400	PASSWORD_IS_REQUIRED	A password is required.
403	PERMISSION_DENIED	The account does not have permission to access this information.
403	QUOTA_EXCEEDED	The quota has been exceeded.
403	RATE_EXCEEDED	The rate has been exceeded.
403	BATCH_LIMIT_EXCEEDED	The campaign exceeds the batch limit of 200.
200	SUCCESS	Success
500	SYSTEM_ERROR_TRY_AGAIN	The request was properly formed, but a server error occurred while processing. Please try the request again.
500	SYSTEM_ERROR_UNKNOWN	There was an unknown server error.

Response Examples

Example 1: JSON Success

"response": {
  "code": "SUCCESS"
  "field": ""
  "message": "Success"
}

Example 2: XML Success

<response>
  <code>SUCCESS</code>
  <field></field>
  <message>Success</message>
</response>

Example 3: JSON Error

"response": {
  "code": "PARAMETER_FORMAT"
  "field": "startIndex"
  "message": "The start index was invalid. Valid values are integers starting at 0."
}

Example 4: XML Error

<response>
  <code>PARAMETER_FORMAT</code>
  <field>startIndex</field>
  <message>The start index was invalid. Valid values are integers starting at 0.</message>
</response>

Example 5: JSON Multiple Result Response

In requests that support multiple operations, responses will generally have HTTP status code 200 and supply CityGrid status codes for each operation result within the response.

{
  "totalNumEntries": 2,
  "totalBudget": 0,
  "campaigns": [
    {
      "name": "21465-27",
      "id": 782,
      "response": {
        "code": "SUCCESS"
        "field": ""
        "message": "Success"
      },
      "budgetAmount": "0",
      "product": "PERFORMANCE",
      "startDate": "20071113",
      "endDate": "",
      "externalId": "",
      "budgetPeriod": "MONTHLY",
      "servingStatus": "CANCELLED",
      "biddingStrategy": "PPE"
    },
    {
      "name": "",
      "id": 0,
      "response": {
        "code": "ENTITY_NOT_FOUND"
        "field" "Campaign Id"
        "message": "The Campaign Id could not be found.",
      },
      "budgetAmount": "",
      "product": "",
      "startDate": "",
      "endDate": "",
      "externalId": "",
      "budgetPeriod": "",
      "servingStatus": "",
      "biddingStrategy": ""
    }
  ]
}

Example 6: XML Multiple Result Response

In requests that support multiple operations, responses will generally have HTTP status code 200 and supply CityGrid status codes for each operation result within the response.

<results>
  <totalBudget>0</totalBudget>
  <totalNumEntries>2</totalNumEntries>
  <campaigns>
    <campaign>
      <budgetAmount>0</budgetAmount>
      <budgetPeriod>MONTHLY</budgetPeriod>
      <endDate></endDate>
      <externalId></externalId>
      <id>782</id>
      <name>21465-27</name>
      <response>
        <code>SUCCESS</code>
        <field></field>
        <message>Success</message>
      </response>
      <servingStatus>CANCELLED</servingStatus>
      <startDate>20071113</startDate>
    </campaign>
    <campaign>
      <budgetAmount></budgetAmount>
      <budgetPeriod></budgetPeriod>
      <endDate></endDate>
      <externalId></externalId>
      <id>0</id>
      <name></name>
      <product></product>
      <response>
        <code>ENTITY_NOT_FOUND</code>
        <field>Campaign Id</field>
        <message>The Campaign Id could not be found.</message>
      </response>
      <servingStatus></servingStatus>
      <startDate></startDate>
    </campaign>
  </campaigns>
</results>