Errors

Errors

An API request may fail due to a request or server error.

Errors are returned using standard HTTP Status Codes. The available status codes are defined by RFC 7231 and registered status codes are listed in the IANA Status Code Registry.

An error will include a response body in JSON format.

Response Status Codes

Status-code element is a three-digit integer code giving the result of the attempt to understand and satisfy the request. HTTP has a set of standard status codes which fall into five categories:

• Informational (1xx)
• Success (2xx)
• Redirection (3xx)
• Client Errors (4xx)
• Server Errors (5xx)

Informational (1xx)

Not currently supported.

Success (2xx)

The following 2xx status codes are supported:

Code	Reason-phrase
200	OK
201	Created
202	Accepted
204	No Content

Redirection (3xx)

Not currently supported.

Client Errors (4xx)

The following 4xx status codes are supported:

Code	Reason-phrase
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
409	Conflict
412	Precondition Failed
413	Payload Too Large
415	Unsupported Media Type

Server Errors (5xx)

The following 5xx status codes are supported:

Code	Reason-phrase
500	Internal Server Error
503	Service Unavailable

Retry Behavior

A 5xx response, or no response at all (a timeout or connection failure), typically indicates a transient condition rather than a problem with the request itself. Retry using an exponential backoff strategy: wait approximately 1 second before the first retry, then 2 seconds, then 4 seconds, capping at 3 to 5 attempts total. Do not retry in a tight loop — immediate retries can fail again or trigger rate limiting.

4xx responses are not transient and should not be retried unmodified. They indicate a problem with the request itself — malformed data, an authorization issue, a conflict — that retrying the identical payload will not resolve.

If the request still fails after the retry cap, treat it as persistent rather than transient and escalate to Apple Business Support. Include:

• The apple-request-id from the response headers, if one was returned
• The specific status code and error message observed
• A sample of the request payload that failed

Response Headers

Name	Description
content-type	REQUIRED. MIME type of the content: application/json
apple-request-id	Unique ID

Example Response Headers

HTTP/1.1 404 Not Found
apple-request-id: 0a8af52f-aa59-4cbd-96a6-bde380fc64ea
content-type: application/json

Response Body

Name	Type	Description
code	string	REQUIRED. May be prefixed with a resource type. Possible values
message	string	Message describing the issue
context	object	Refer to Context
details	object	Refer to Details

Context

Name	Type	Description
key	string	A name-value map of a variable and its value necessary to construct the message. A null value indicates the referenced field was not included in the request body, as distinct from being present with a non-matching value. REQUIRED when message includes dynamic content

note

Refer to FAQs for additional information about how a partner may use context

Details

Name	Type	Description
createdDate	dateTime	Date and time the error was recorded
submitted	array	Field-value pairs representing the values submitted in the request. Refer to Details Item
expected	array	Field-value pairs representing the values expected by the API. Refer to Details Item
compared	array	Field-value pairs representing existing resource values compared against the request. Refer to Details Item

Details Item

Name	Type	Description
field	string	Name of the field
value	string	Value of the field

Example Response Body

[
  {
    "code": "LOCATION__NOT_FOUND",
    "message": "Resource not found for Apple-generated '{{id}}'",
    "context": {
      "id": "9467895078742654451"
    }
  }
]

HTTP Status Code and Response Body Code Combinations

View Combinations

HTTP Status Code	Response Body Code
400 Bad Request	INVALID_REQUEST_PARAMETER
400 Bad Request	INVALID_RESOURCE_TYPE
400 Bad Request	{RESOURCE-TYPE}__ALREADY_ACCEPTED
400 Bad Request	{RESOURCE-TYPE}__ALREADY_EXISTS
400 Bad Request	{RESOURCE-TYPE}__CLOSED
400 Bad Request	{RESOURCE-TYPE}__HAS_ACTIVE_MANAGER_USER
400 Bad Request	{RESOURCE-TYPE}__HAS_NO_NEW_CHANGES
400 Bad Request	{RESOURCE-TYPE}__ID_MISMATCH
400 Bad Request	{RESOURCE-TYPE}__IMAGEID_ALREADY_HAS_ANOTHER_INTENT
400 Bad Request	{RESOURCE-TYPE}__IS_MATCHED
400 Bad Request	{RESOURCE-TYPE}__MARKED_DELETED
400 Bad Request	{RESOURCE-TYPE}__NOT_FOUND
400 Bad Request	{RESOURCE-TYPE}__ORG_TYPE_NOT_PERMITTED
400 Bad Request	{RESOURCE-TYPE}__PARTNER_ID_MARKED_DELETED
400 Bad Request	{RESOURCE-TYPE}__RESOURCE_NOT_ACTIVATED
400 Bad Request	{RESOURCE-TYPE}__UPDATE_IN_PROGRESS
400 Bad Request	RSQL_PARSING_ERROR
403 Forbidden	BRAND_ID_REQUIRED_FOR_AUTHORIZATION
403 Forbidden	NOT_AUTHORIZED
403 Forbidden	ORG_TYPE_NOT_AUTHORIZED
403 Forbidden	{RESOURCE-TYPE}__OPERATION_NOT_ALLOWED_FOR_RESOURCE_TYPE
404 Not Found	{RESOURCE-TYPE}__MARKED_DELETED
404 Not Found	{RESOURCE-TYPE}__NOT_FOUND
404 Not Found	{RESOURCE-TYPE}__PARTNER_ID_MARKED_DELETED
404 Not Found	{RESOURCE-TYPE}__PARTNER_ID_NOT_FOUND
404 Not Found	{RESOURCE-TYPE}__REQUEST_FAILED
409 Conflict	{RESOURCE-TYPE}__CREATION_IN_PROGRESS
412 Precondition Failed	{RESOURCE-TYPE}__INCORRECT_ETAG
413 Payload Too Large	PAYLOAD TOO LARGE
415 Unsupported Media Type	UNSUPPORTED_CONTENT_TYPE
428 Precondition Required	REQUIRED_HEADER_MISSING
429 Too Many Requests	TOO_MANY_REQUESTS
500 Internal Server Error	INTERNAL_SERVER_ERROR
500 Internal Server Error	PAYLOAD-TOO-LARGE
503 Service Unavailable	-N/A-

400 Bad Request

Already Accepted

Code Description
Attempt to contest an Apple Override after it is already accepted.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Contest
Apple Override	✓

Example Response Body

[
  {
    "code": "APPLE_OVERRIDE__ALREADY_ACCEPTED",
    "message": "Change to resource with Apple-generated '{{id}}' already accepted",
    "context": {
      "id": "30eaaef3-688c-4e82-8547-7c64c1181ffa"
    }
  }
]

Closed

Code Description
Attempt to accept an Apple Override after it transitioned to CLOSED. An Apple Override closes when the location changes again before the user responds, superseding the override being accepted.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Accept
Apple Override	✓

Example Response Body

[
  {
    "code": "APPLE_OVERRIDE__CLOSED",
    "message": "Apple override with Apple-generated '{{id}}' is closed. If the location has changed, check notifications/feedback for a new override; otherwise no action is needed",
    "context": {
      "id": "30eaaef3-688c-4e82-8547-7c64c1181ffa"
    }
  }
]

Already Exists

Code Description

• Attempt to create a resource using a partner provided ID referenced in the body of the request that's associated with an existing resource. Partner provided ID in message may be:

• partnersAssetId (brand asset or location asset)
• partnersBrandId
• partnersLocationId
• partnersReviewId

• partnersAssetId (brand asset or location asset)
• partnersBrandId
• partnersLocationId

• Attempt to create a resource using the resource named in the URL path that's associated with an existing resource.
• Attempt to create a resource using values which match an already existing resource. (For Location, refer to Is Matched)

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create
Aggregate Rating	✓
Brand	✓
Brand Asset	✓
Location	✓
Location Asset	✓
Review	✓

Resource Type	Create
Brand	✓
Brand Asset	✓
Location	✓
Location Asset	✓

Example Response Body

[
  {
    "code": "BRAND__ALREADY_EXISTS",
    "message": "Resource already exists with '{{partnersBrandId}}'",
    "context": {
      "partnersBrandId": "9467895078742653232"
    }
  }
]

Update In Progress

Code Description
Attempt to update a resource when a previous request is already pending completion.

Resource Type	Update
Review	✓

Example Response Body

[
  {
    "code": "REVIEW__UPDATE_IN_PROGRESS",
    "message": "Update of resource is pending completion",
    "context": {
      "partnersReviewId": "7ef2d2b4-b6e3-11ed-afa1-0242ac120002"
    }
  }
]

Organization Type Not Permitted

Code Description
Attempt to call a web service operation that's not eligible for use by the organization type that's originating the request.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Get	Update	Delete	Deactivate	Extend	Service Restricted To
Aggregate Rating	✓	✓	✓	✓	N/A	N/A	Non-delegated partner
Email ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Review	✓	✓	✓	✓	N/A	N/A	Non-delegated partner
Showcase	✓	✓	✓	✓	✓	✓	Location owner/delegated partner
Showcase Creative	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner

Resource Type	Create	Get	Update	Delete	Deactivate	Extend	Service Restricted To
Caller ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Email ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Showcase	✓	✓	✓	✓	✓	✓	Location owner/delegated partner
Showcase Creative	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner

Resource Type	Create	Get	Update	Delete	Deactivate	Extend	Service Restricted To
Email ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Showcase	✓	✓	✓	✓	✓	✓	Location owner/delegated partner
Showcase Creative	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner

Resource Type	Create	Get	Update	Delete	Deactivate	Extend	Service Restricted To
Aggregate Rating	✓	✓	✓	✓	N/A	N/A	Non-delegated partner
Caller ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Email ID	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner
Review	✓	✓	✓	✓	N/A	N/A	Non-delegated partner
Showcase	✓	✓	✓	✓	✓	✓	Location owner/delegated partner
Showcase Creative	✓	✓	✓	✓	N/A	N/A	Location owner/delegated partner

Example Response Body

[
  {
    "code": "SHOWCASE__ORG_TYPE_NOT_PERMITTED",
    "message": "Organization '{{orgId}}' is an organization type which is not permitted access to this service per Apple Business policy",
    "context": {
      "orgId": "9467895078742656751"
    }
  }
]

Has Active Manager User

Code Description
Attempt to perform an operation on a resource when an active manager user is associated with the resource.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Delete
Brand	✓
Organization	✓

Example Response Body One

[
  {
    "code": "BRAND__HAS_ACTIVE_MANAGER_USER",
    "message": "Requested operation for '{{id}}' cannot be completed when resource has active manager user",
    "context": {
      "id": "9467895078742653232"
    }
  }
]

Example Response Body Two

[
  {
    "code": "ORG__HAS_ACTIVE_MANAGER_USER",
    "message": "Requested operation for '{{id}}' cannot be completed when resource has active manager user",
    "context": {
      "id": "9467895078742653232"
    }
  }
]

Has No New Changes

Code Description
Attempt to update a resource with details that exactly match a previous version. Previous version may be FAILED, PUBLISHED, or REJECTED. The error surfaces the etag value that matched a previous request.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Update	Comment
Brand	✓	partnersBrandVersion is excluded from matching process
Location	✓	partnersLocationVersion is excluded from matching process
Location Asset	✓	Match is determined after data normalization — the submitted asset may appear to differ but resolve to the same stored state

Example Response Bodies

Example Response Body One

[
  {
    "code": "BRAND__HAS_NO_NEW_CHANGES",
    "message": "Resource has no new changes. Data exactly matches content in a previous request",
    "context": {
      "field": "etag",
      "value": "bd498b0e-31aa-11f0-9cd2-0242ac120002"
    }
  }
]

Example Response Body Two

[
  {
    "code": "LOCATION__HAS_NO_NEW_CHANGES",
    "message": "Resource has no new changes. Data exactly matches content in a previous request",
    "context": {
      "field": "etag",
      "value": "7ef2d2b4-b6e3-11ed-afa1-0242ac120002"
    }
  }
]

Example Response Body Three

[
  {
    "code": "LOCATION_ASSET__HAS_NO_NEW_CHANGES",
    "message": "After processing, the resulting asset state is identical to what is already stored — no update was performed",
    "context": {
      "field": "etag",
      "value": "c3d4e5f6-b6e3-11ed-afa1-0242ac120002"
    }
  }
]

Image ID Already Has Another Intent

Code Description
Attempt to create a resource using an image ID referenced in the body of the request that's associated with an existing resource with a different intent.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Update	Undelete
Location Asset	✓	✓	✓

Example Response Body

[
  {
    "code": "LOCATION_ASSET__IMAGEID_ALREADY_HAS_ANOTHER_INTENT",
    "message": "Location asset with different intent already exists and references Apple-generated `imageId` '{{imageId}}'",
    "context": {
      "imageId": "55084212-0980-11f0-9cd2-0242ac120002"
    }
  }
]

ID Mismatch

Code Description

• Attempt to update a resource using an Apple-generated ID referenced in the URL path that does not match the Apple-generated ID referenced in the body of the request.
• Attempt to update a resource using an Apple-generated ID referenced in the URL path when an Apple-generated ID is absent from the body of the request.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Update	Deactivate	Extend
Aggregate Rating	✗	N/A	N/A
Brand	✓	N/A	N/A
Brand Asset	✓	N/A	N/A
Email ID	✓	N/A	N/A
Location Asset	✓	N/A	N/A
Location	✓	N/A	N/A
Review	✓	N/A	N/A
Showcase	✓	✓	✓
Showcase Creative	✓	N/A	N/A

Resource Type	Update	Deactivate	Extend
Brand	✓	N/A	N/A
Brand Asset	✓	N/A	N/A
Caller ID	✓	N/A	N/A
Email ID	✓	N/A	N/A
Location Asset	✓	N/A	N/A
Location	✓	N/A	N/A
Showcase	✓	✓	✓
Showcase Creative	✓	N/A	N/A

Resource Type	Update	Deactivate	Extend
Brand	✓	N/A	N/A
Brand Asset	✓	N/A	N/A
Email ID	✓	N/A	N/A
Location Asset	✓	N/A	N/A
Location	✓	N/A	N/A
Showcase	✓	✓	✓
Showcase Creative	✓	N/A	N/A

Resource Type	Update	Deactivate	Extend
Aggregate Rating	✗	N/A	N/A
Brand	✓	N/A	N/A
Brand Asset	✓	N/A	N/A
Caller ID	✓	N/A	N/A
Email ID	✓	N/A	N/A
Location Asset	✓	N/A	N/A
Location	✓	N/A	N/A
Review	✓	N/A	N/A
Showcase	✓	✓	✓
Showcase Creative	✓	N/A	N/A

Example Response Body One

[
  {
    "code": "LOCATION__ID_MISMATCH",
    "message": "'{{pathId}}' referenced in URL and request '{{bodyId}}' do not match",
    "context": {
      "pathId": "184916987752743193",
      "bodyId": "184916987752743199"
    }
  }
]

Example Response Body Two

[
  {
    "code": "LOCATION__ID_MISMATCH",
    "message": "'{{pathId}}' referenced in URL and request '{{bodyId}}' do not match",
    "context": {
      "pathId": "184916987752743193",
      "bodyId": null
    }
  }
]

Invalid Data Type

Code Description
Attempt to create or update a resource using a JSON body that includes an incorrect data type. For example, a value presented as a string when expected as an integer data type.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Aggregate Rating	✓	✓	N/A	N/A	N/A	N/A
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	✗	✗	N/A	N/A	✓	✓
Review	✓	✓	N/A	N/A	N/A	N/A
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Caller ID	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	✗	✗	N/A	N/A	✓	✓
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	✗	✗	N/A	N/A	✓	✓
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Aggregate Rating	✓	✓	N/A	N/A	N/A	N/A
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Caller ID	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	✗	✗	N/A	N/A	✓	✓
Review	✓	✓	N/A	N/A	N/A	N/A
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Response Template

[
  {
    "code": "INVALID_DATA_TYPE",
    "message": "Invalid {data-type-used} data type. {data-type-required} is required",
    "context": {
      "field": "{/path/to/field}",
      "value": "{field_value}"
    }
  }
]

{data-type-used}	Description
VALUE_BOOLEAN	Invalid data type (Boolean)
VALUE_DATE_TIME	Invalid data type (Date/Time)
VALUE_NUMBER_FLOAT	Invalid data type (Float)
VALUE_NUMBER_INTEGER	Invalid data type (Integer)
VALUE_STRING	Invalid data type (String)
VALUE_URL	Invalid data type (URL)

{data-type-required}	Description
Boolean	Valid data type (Boolean)
Date/Time	Valid data type (Date/Time)
Float	Valid data type (Float)
Integer	Valid data type (Integer)
String	Valid data type (String)
URL	Valid data type (URL)

Example Response Body

[
  {
    "code": "INVALID_DATA_TYPE",
    "message": "Invalid 'VALUE_NUMBER_FLOAT' data type. String data type is required",
    "context": {
      "field": "$.locationDetails.displayPoint.coordinates.latitude",
      "value": "40.783683"
    }
  }
]

Invalid Request Parameter

Code Description
Attempt to get a collection of resources using a limit value that is not within a supported range.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Get
Aggregate Rating	✗
Brand	✓
Brand Asset	✓
Email ID	✓
Location	✓
Location Asset	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location	✓
Location Asset	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Brand	✓
Brand Asset	✓
Email ID	✓
Location	✓
Location Asset	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Aggregate Rating	✗
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location	✓
Location Asset	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Example Response Body

[
  {
    "code": "INVALID_REQUEST_PARAMETER",
    "message": "Invalid request parameter 'limit'"
  }
]

Invalid Resource Type

Code Description
Attempt to get a collection of resources using a resource type value that is not valid or unsupported by the API version.

Code may be returned by the following web service operations:

Resource Type	Get
Feedback	✓
Notifications	✓

Example Response Body

[
  {
    "code": "INVALID_RESOURCE_TYPE",
    "message": "'resourceType' value '{{value}}' is not valid or unsupported by API version",
    "context": {
      "field": "resourceType",
      "value": "BUSINESS"
    },
    "details": {
      "createdDate": "2026-11-10T11:36:02.00Z",
      "submitted": [
        {
          "field": "resourceType",
          "value": "BUSINESS"
        }
      ],
      "expected": [
        {
          "field": "resourceType",
          "value": "BRAND"
        }
      ]
    }
  }
]

Is Matched

Code Description
Attempt to create or update a resource using values which match an existing resource or a previous version.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Update
Location	✓	N/A

Matching Criteria - Location

Property	Rule
$.locationDetails.categories[]	Matches at least one value
$.locationDetails.displayNames[].name	primary = true
mainAddress.fullAddress	structuredAddress when fullAddress is not present
phoneNumbers[].phoneNumber	primary = true

Resource Type	Create	Update	Comment
Location	✓	N/A	—
Review	✓	✓	Update: partnersReviewId is excluded from matching process

Matching Criteria - Location

Property	Rule
$.locationDetails.categories[]	Matches at least one value
$.locationDetails.displayNames[].name	primary = true
mainAddress.fullAddress	structuredAddress when fullAddress is not present
phoneNumbers[].phoneNumber	primary = true

Matching Criteria - Review

Property
$.orgId
$.locationId
$.reviewDetails.dateAdded
$.reviewDetails.review.author.givenName
$.reviewDetails.review.reviewBody

Example Response Body (Location)

[
  {
    "code": "LOCATION__IS_MATCHED",
    "message": "Resource has comparable representation",
    "context": {},
    "details": {
      "createdDate": "2026-05-20T11:36:02.00Z",
      "compared": [
        {
          "field": "id",
          "value": "9467895078742654451"
        }
      ]
    }
  }
]

Example Response Body (Review)

[
  {
    "code": "REVIEW__IS_MATCHED",
    "message": "Resource has comparable representation",
    "context": {},
    "details": {
      "createdDate": "2026-10-10T11:36:02.00Z",
      "compared": [
        {
          "field": "id",
          "value": "9467895078742654975"
        }
      ]
    }
  }
]

Marked Deleted

Code Description

• Attempt to create or update a resource which includes, in the body of the request, an Apple-generated ID that references a resource which is deleted.
• Attempt to create or update a sub-resource when a resource identified in the URL path is deleted.
• Attempt to create or update a resource that has a dependency upon a resource which is deleted.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Update	Referenced Resource/Dependency
Aggregate Rating	N/A	N/A	N/A
Brand	N/A	N/A	N/A
Brand Asset	✓	✓	Image (via imageId)
Email ID	✓	✓	Brand Asset
Location	✓	✓	Brand (via brandId)
Location Asset	✓	✓	Image (via imageId)
Review	N/A	N/A	N/A
Showcase	✓	✓	Location (via resourceId)
Showcase Creative	✓	✓	Image (via Photo id)

Resource Type	Create	Update	Referenced Resource/Dependency
Brand	N/A	N/A	N/A
Brand Asset	✓	✓	Image (via imageId)
Caller ID	✓	✓	Brand Asset
Email ID	✓	✓	Brand Asset
Location	✓	✓	Brand (via brandId)
Location Asset	✓	✓	Image (via imageId)
Showcase	✓	✓	Location (via resourceId)
Showcase Creative	✓	✓	Image (via Photo id)

Resource Type	Create	Update	Referenced Resource/Dependency
Brand	N/A	N/A	N/A
Brand Asset	✓	✓	Image (via imageId)
Email ID	✓	✓	Brand Asset
Location	✓	✓	Brand (via brandId)
Location Asset	✓	✓	Image (via imageId)
Showcase	✓	✓	Location (via resourceId)
Showcase Creative	✓	✓	Image (via Photo id)

Resource Type	Create	Update	Referenced Resource/Dependency
Aggregate Rating	N/A	N/A	N/A
Brand	N/A	N/A	N/A
Brand Asset	✓	✓	Image (via imageId)
Caller ID	✓	✓	Brand Asset
Email ID	✓	✓	Brand Asset
Location	✓	✓	Brand (via brandId)
Location Asset	✓	✓	Image (via imageId)
Review	N/A	N/A	N/A
Showcase	✓	✓	Location (via resourceId)
Showcase Creative	✓	✓	Image (via Photo id)

Example Response Body

[
  {
    "code": "LOCATION__MARKED_DELETED",
    "message": "Resource marked deleted for Apple-generated '{{id}}'",
    "context": {
      "id": "9467895078742656755"
    }
  }
]

Not Found

Code Description
Attempt to update a resource using an Apple-generated ID referenced in the body of the request which is not found.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Update
Aggregate Rating	N/A
Brand	✓
Brand Asset	✓
Email ID	✓
Location Asset	✓
Location	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Update
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location Asset	✓
Location	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Update
Brand	✓
Brand Asset	✓
Email ID	✓
Location Asset	✓
Location	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Update
Aggregate Rating	N/A
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location Asset	✓
Location	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Example Response Body

[
  {
    "code": "SHOWCASE__NOT_FOUND",
    "message": "Resource not found for Apple-generated '{{id}}'",
    "context": {
      "id": "9467895078742653901"
    }
  }
]

note

Refer to 404 Not Found (Not Found) for the same code whose context is the URL, not the request body

Parsing Error

Code Description
Attempt to create or update a resource using a JSON body that exhibits any of these characteristics:

• Malformed JSON - Structure does not match the specification
• Unrecognized property - Key is present which is not defined in the specification
• Incorrect data type - For example, a value presented as a string when expected as an integer data type, and so on

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Aggregate Rating	✓	✓	N/A	N/A	N/A	N/A
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	N/A	N/A	N/A	N/A	✓	✓
Review	✓	✓	N/A	N/A	N/A	N/A
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Caller ID	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	N/A	N/A	N/A	N/A	✓	✓
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	N/A	N/A	N/A	N/A	✓	✓
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Resource Type	Create	Update	Deactivate	Extend	Import	Upload
Aggregate Rating	✓	✓	N/A	N/A	N/A	N/A
Brand	✓	✓	N/A	N/A	N/A	N/A
Brand Asset	✓	✓	N/A	N/A	N/A	N/A
Caller ID	✓	✓	N/A	N/A	N/A	N/A
Email ID	✓	✓	N/A	N/A	N/A	N/A
Location Asset	✓	✓	N/A	N/A	N/A	N/A
Location	✓	✓	N/A	N/A	N/A	N/A
Media	N/A	N/A	N/A	N/A	✓	✓
Review	✓	✓	N/A	N/A	N/A	N/A
Showcase	✓	✓	✓	✓	N/A	N/A
Showcase Creative	✓	✓	N/A	N/A	N/A	N/A

Example Response Body

[
  {
    "code": "PARSING_ERROR",
    "message": "Request contains malformed json"
  }
]

Partner ID Marked Deleted

Code Description
Attempt to create a resource using a partner provided ID referenced in the body of the request that's associated with an existing resource that's marked as deleted. Partner provided ID in message may be:

• partnersAssetId (location asset)
• partnersLocationId
• partnersReviewId

• partnersAssetId (location asset)
• partnersLocationId

Code may be returned for these resource types and by the following web service operations:

Resource Type	Create
Aggregate Rating	N/A
Brand	N/A
Brand Asset	N/A
Location	✓
Location Asset	✓
Review	✓

Resource Type	Create
Brand	N/A
Brand Asset	N/A
Location	✓
Location Asset	✓

Example Response Body

[
  {
    "code": "LOCATION_ASSET__PARTNER_ID_MARKED_DELETED",
    "message": "Resource with '{{partnersAssetId}}' is marked deleted",
    "context": {
      "partnersAssetId": "9467895078742653110"
    }
  }
]

Resource Not Activated

Code Description
Attempt to call a web service operation for a showcase or showcase creative under a brand that is not activated. The brand is identified by brandId in the URL path.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Operations	Resource Dependency
Showcase	All showcase operations	Brand (via brandId)
Showcase Creative	All showcase creative operations, including Get Calls to Action	Brand (via brandId)

Example Response Body One

[
  {
    "code": "SHOWCASE__RESOURCE_NOT_ACTIVATED",
    "message": "Referenced resource is a dependency. '{{field}}' referencing '{{value}}' is not activated. Try again later",
    "context": {
      "field": "brandId",
      "value": "9467895078742654921"
    }
  }
]

Example Response Body Two

[
  {
    "code": "SHOWCASE_CREATIVE__RESOURCE_NOT_ACTIVATED",
    "message": "Referenced resource is a dependency. '{{field}}' referencing '{{value}}' is not activated. Try again later",
    "context": {
      "field": "brandId",
      "value": "9467895078742654921"
    }
  }
]

RSQL Parsing Error

Code Description
Attempt to request a resource using an RSQL filter that is unrecognized, incorrectly structured, or not supported.

Example Response Body

[
  {
    "code": "RSQL_PARSING_ERROR",
    "message": "The query could not be parsed"
  }
]

403 Forbidden

Operation Not Allowed for Resource Type

Code Description
Attempt to call a web service operation which is not allowed for the resource type.

Code may be returned for this resource type and by the following web service operations:

Resource Type	Added Locations	Removed Locations	Comment
Location Group	✓	✓	Triggered when resource type is STATIC

Example Response Body

[
  {
    "code": "LOCATION_GROUP__OPERATION_NOT_ALLOWED_FOR_RESOURCE_TYPE",
    "message": "Operation is only permitted for `DYNAMIC` resource type."
  }
]

Organization Type Not Authorized

Code Description
Attempt to call a web service operation that's not eligible for use by the org type that's originating the request.

Example Response Body

[
  {
    "code": "ORG_TYPE_NOT_AUTHORIZED",
    "message": "Method and specified resource is not available to organization type"
  }
]

Not Authorized

Code Description
Attempt to call a web service operation by a system account whose role assignment(s) do not include the permissions necessary to allow action against a resource.

Example Response Body

[
  {
    "code": "NOT_AUTHORIZED",
    "message": "Role is not authorized to make request for organization '{{id}}'",
    "context": {
      "id": "9467895078742653901"
    }
  }
]

Brand ID Required for Authorization

Code Description
Attempt to call a web service operation for a resource that requires brand-level access, without supplying the brandId needed to perform that access check.

Example Response Body

[
  {
    "code": "BRAND_ID_REQUIRED_FOR_AUTHORIZATION",
    "message": "'brandId' is required to authorize this request"
  }
]

404 Not Found

Marked Deleted

Code Description

• Attempt to delete, update, or get details about a resource using an Apple-generated ID, referenced in the URL path, that's associated with a resource that's deleted.
• Attempt to delete, update, or get details about a resource named in the URL path that's deleted.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Get by ID	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	✓	N/A
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Review	✓	✓	✓	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Caller ID	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	✓	N/A
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Caller ID	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Review	✓	✓	✓	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Example Response Body

[
  {
    "code": "LOCATION__MARKED_DELETED",
    "message": "Resource marked deleted for Apple-generated '{{id}}'",
    "context": {
      "id": "9467895078742656755"
    }
  }
]

Not Found

Code Description

• Attempt to delete, update, or get details about a resource, using an Apple-generated ID referenced in the URL path, that cannot be found.
• Attempt to call a service using a orgId, referenced in the URL path, that cannot be found.
• Attempt to delete, update, or get details about a resource named in the URL path which cannot be found.

note

When orgId is not matched, the code prefix is the target resource type. For example, if orgId in a request to Get a location is unmatched, while locationId might be valid in the correct organization data context, LOCATION__NOT_FOUND is returned.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Get by ID	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	✓	N/A
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Review	✓	✓	✓	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Caller ID	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Resource Type	Get by ID	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	✓	N/A
Brand	✓	✓	✓	N/A
Brand Asset	✓	✓	✓	N/A
Caller ID	✓	✓	✓	N/A
Email ID	✓	✓	✓	N/A
Location	✓	✓	✓	✓
Location Asset	✓	✓	✓	N/A
Media (Metadata)	✓	N/A	N/A	N/A
Review	✓	✓	✓	N/A
Showcase	✓	✓	✓	N/A
Showcase Creative	✓	✓	✓	N/A

Example Response Body

[
  {
    "code": "LOCATION__NOT_FOUND",
    "message": "Resource not found for '{{id}}'",
    "context": {
      "id": "9467895078742653168"
    }
  }
]

Partner ID Not Found

Code Description
Attempt to get details about a resource, using a Partner ID referenced in the URL path, that cannot be found.
Code may be returned for these resource types and by the following web service operations:

Resource Type	Get by Partner ID
Location	✓
Review	✓

Resource Type	Get by Partner ID
Location	✓

Example Response Body

[
  {
    "code": "LOCATION__PARTNER_ID_NOT_FOUND",
    "message": "Resource not found for '{{partnersLocationId}}'",
    "context": {
      "partnersLocationId": "a9f69b61-ee88-4a8b-b173-fa2abc0e5a16"
    }
  }
]

Request Failed

Code Description
Failure condition which is not within the scope of any existing error code

Example Response Body

[
  {
    "code": "REQUEST_FAILED",
    "message": "Contact support team"
  }
]

409 Conflict

Creation In Progress

Code Description
Attempt to create a resource when a previous request is already pending completion.

Resource Type	Create
Brand	✓

Example Response Body

[
  {
    "code": "BRAND__CREATION_IN_PROGRESS",
    "message": "Creation of resource is pending completion",
    "context": {
      "partnersBrandId": "7ef2d2b4-b6e3-11ed-afa1-0242ac120002"
    }
  }
]

Creation In Progress

Code Description
Attempt to create a resource when a previous request is already pending completion.

Resource Type	Create
Brand	✓
Review	✓

Example Response Body

[
  {
    "code": "REVIEW__CREATION_IN_PROGRESS",
    "message": "Creation of resource is pending completion",
    "context": {
      "partnersReviewId": "7ef2d2b4-b6e3-11ed-afa1-0242ac120002"
    }
  }
]

412 Precondition Failed

Incorrect ETag

Code Description

• Attempt to update a resource whose etag value that does not match the etag in an If-Match header.
• Attempt to delete or update a resource using an etag value that cannot be found.
• Provided etag value is not valid. For example, is not UUID-compliant or is an empty string.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	N/A
Brand	✓	✓	N/A
Brand Asset	✓	✓	N/A
Email ID	✓	✓	N/A
Location	✓	✓	✓
Location Asset	✓	✓	N/A
Media (Metadata)	N/A	N/A	N/A
Review	✓	✓	N/A
Showcase	✓	✓	N/A
Showcase Creative	✓	✓	N/A

Resource Type	Update	Delete	Close and Delete
Brand	✓	✓	N/A
Brand Asset	✓	✓	N/A
Caller ID	✓	✓	N/A
Email ID	✓	✓	N/A
Location	✓	✓	✓
Location Asset	✓	✓	N/A
Media (Metadata)	N/A	N/A	N/A
Showcase	✓	✓	N/A
Showcase Creative	✓	✓	N/A

Resource Type	Update	Delete	Close and Delete
Brand	✓	✓	N/A
Brand Asset	✓	✓	N/A
Email ID	✓	✓	N/A
Location	✓	✓	✓
Location Asset	✓	✓	N/A
Media (Metadata)	N/A	N/A	N/A
Showcase	✓	✓	N/A
Showcase Creative	✓	✓	N/A

Resource Type	Update	Delete	Close and Delete
Aggregate Rating	✓	✓	N/A
Brand	✓	✓	N/A
Brand Asset	✓	✓	N/A
Caller ID	✓	✓	N/A
Email ID	✓	✓	N/A
Location	✓	✓	✓
Location Asset	✓	✓	N/A
Media (Metadata)	N/A	N/A	N/A
Review	✓	✓	N/A
Showcase	✓	✓	N/A
Showcase Creative	✓	✓	N/A

Example Response Body

[
  {
    "code": "BRAND__INCORRECT_ETAG",
    "message": "Resource not found for '{{etag}}'. Please sync resource to latest ETag",
    "context": {
      "etag": "f277e614-f94c-48f0-b4e7-c1c1f0c7d907"
    }
  }
]

413 Payload Too Large

Code Description
Request response is too large.

Code may be returned for these resource types and by the following web service operations:

Resource Type	Get
Aggregate Rating	N/A
Brand	✓
Brand Asset	✓
Email ID	✓
Location	✓
Location Asset	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location	✓
Location Asset	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Brand	✓
Brand Asset	✓
Email ID	✓
Location	✓
Location Asset	✓
Showcase	✓
Showcase Creative	✓

Resource Type	Get
Aggregate Rating	N/A
Brand	✓
Brand Asset	✓
Caller ID	✓
Email ID	✓
Location	✓
Location Asset	✓
Review	✓
Showcase	✓
Showcase Creative	✓

Example Response Body

[
  {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Response is too large. Paginate with lower limit"
  }
]

415 Unsupported Media Type

Unsupported Media Type

Code Description
Attempt to submit a resource using a format that is not supported.

Example Response Body

[
  {
    "code": "UNSUPPORTED_CONTENT_TYPE",
    "message": "Content type is not supported. Refer to API Docs"
  }
]

428 Precondition Required

Required Header Missing

Code Description
Attempt to call a web service operation when required header is missing. A header is defined as "...a name followed by a colon (":") and the field value." (Reference: RFC 2616)

When a required header is present, but is not accompanied by a value, 428 Precondition Required shall be returned.

Example Response Body

[
  {
    "code": "REQUIRED_HEADER_MISSING",
    "message": "Required header field missing. Refer to API Docs"
  }
]

429 Too Many Requests

Code Description
Successive attempts to call a web service operation which exceeds a rate limit.

Example Response Body

[
  {
    "code": "TOO_MANY_REQUESTS",
    "message": "Too Many Requests"
  }
]

500 Internal Server Error

Internal Server Error

Code Description
Server encountered an unexpected condition that prevented it from fulfilling the request.

Example Response Body

[
  {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal Server Error"
  }
]

503 Service Unavailable

Description
Server is not ready to handle the request. Possible causes:

• Response includes headers, only. No response body was provided.
• Request to a v1 endpoint when v3 was intended.

HTTP Status Codes

Status Code	Reason-Phrase	Description
400	Bad Request	Reference
401	Unauthorized	Reference
403	Forbidden	Reference
404	Not Found	Reference
405	Method Not Allowed	Reference
409	Conflict	Reference
412	Precondition Failed	Reference
413	Payload Too Large	Reference
415	Unsupported Media Type	Reference
428	Precondition Required	Reference
429	Too Many Requests	Reference
500	Internal Server Error	Reference
503	Service Unavailable	Reference

Code Prefixes

Prefix
AGGREGATE_RATING__
BRAND__
BRAND_ASSET__
BUSINESS_EMAIL_ID__
INSIGHTS__
MEDIA__
LOCATION__
LOCATION_ASSET__
LOCATION_GROUP__
FEEDBACK__
NOTIFICATION__
REVIEW__
SHOWCASE__
SHOWCASE_CREATIVE__

Prefix
BRAND__
BRAND_ASSET__
BUSINESS_CALLER_ID__
BUSINESS_EMAIL_ID__
INSIGHTS__
MEDIA__
LOCATION__
LOCATION_ASSET__
LOCATION_GROUP__
FEEDBACK__
NOTIFICATION__
SHOWCASE__
SHOWCASE_CREATIVE__

Prefix
APPLE_OVERRIDE__
BRAND__
BRAND_ASSET__
BUSINESS_EMAIL_ID__
INSIGHTS__
MEDIA__
LOCATION__
LOCATION_ASSET__
LOCATION_GROUP__
FEEDBACK__
NOTIFICATION__
SHOWCASE__
SHOWCASE_CREATIVE__