Error (JSON)

The error structure is the same across all APIs. Noteworthy elements are as follows.


The Error object has the following specification.

Member Type Description
ErrorCode String The error code, as described in the following table of error codes.
Description String A description of the error code. This description is meant to be used by the application developer to understand the issue, but shouldn't be displayed as-is to the end user.
Message String A more contextual message describing what may have gone wrong.

These error structures can be optionally embedded in any Groove API service response. If an error is reported, the Error.ErrorCode and Error.Description elements will always be provided.

Error codes

Error codes can be used to display custom error messages to the user.

Category Name Default HTTP code Description
Input validation MISSING_INPUT_PARAMETER 400 Bad Request Missing or empty mandatory parameter.
Input validation INVALID_INPUT_PARAMETER 400 Bad Request Invalid parameter value.
Input validation INCOMPATIBLE_INPUT_PARAMETERS 400 Bad Request Incompatible parameters.
Input validation INVALID_COUNTRY 400 Bad Request The requested functionality is not available in this region
Input validation CONTINUATION_TOKEN_INVALID_ERROR 400 Bad Request The continuation token provided is incorrect.
Input validation UNAUTHORIZED_INPUT_PARAMETER 200 OK Unauthorized input parameter
Input validation UNAUTHORIZED_API_METHOD 403 Forbidden Unauthorized API method
Authentication ACCESS_TOKEN_MISSING 401 Unauthorized Groove MSA access token required.
Authentication ACCESS_TOKEN_INVALID 401 Unauthorized Invalid Azure Marketplace token.
Authentication ACCESS_TOKEN_EXPIRED 401 Unauthorized Expired Azure Marketplace token.
Authentication ACCESS_TOKEN_INVALID_SUBSCRIPTION 401 Unauthorized Azure Marketplace client ID is not a subscriber to the Groove data offer.
Authentication ACCESS_TOKEN_VALIDATION_ERROR 500 Internal Server Error Unexpected error while validating Azure Marketplace token.
Authentication ACCESS_TOKEN_SUBSCRIPTION_VALIDATION_ERROR 500 Internal Server Error Unexpected error while validating Azure Marketplace subscription status.
Authentication INVALID_AUTHORIZATION_HEADER 401 Unauthorized Missing or invalid authorization header
Authentication AUTHORIZATION_TOKEN_EXPIRED 401 Unauthorized User's authorization token expired. You need to obtain a new one.
Authentication MSA_SCOPE_REQUIRES_USER_CONSENT 401 Unauthorized User hasn't accepted the necessary Microsoft account scopes. Force the user to sign-in again.
Authentication NO_MUSIC_PASS_SUBSCRIPTION 403 Forbidden The user does not have a Groove Music subscription
Catalog errors CATALOG_INVALID_DATA 200 OK Error while reading catalog data; some results may be missing.
Catalog errors CATALOG_NO_RESULT 404 Not Found Item does not exist.
Catalog errors CATALOG_UNAVAILABLE 502 Bad Gateway No response from catalog.
Collection errors COLLECTION_INVALID_DATA 200 OK Error while reading collection data, some results may be missing or incomplete
Collection errors COLLECTION_SOME_OPERATIONS_FAILED 200 OK Some of the operations failed
Collection errors COLLECTION_INVALID_PLAYLIST_REORDER 400 Bad Request Invalid playlist reorder operation
Collection errors COLLECTION_FULL 400 BadRequest User's collection is full
Collection errors COLLECTION_PLAYLIST_FULL 400 BadRequest This playlist is full
Collection errors COLLECTION_INVALID_OPERATION 400 BadRequest This operation is not supported
Collection errors COLLECTION_INVALID_ID 400 BadRequest Invalid collection id for this operation
Collection errors COLLECTION_INVALID_PLAYLIST_INFO 400 BadRequest Required playlist information is missing
Collection errors COLLECTION_NO_RESULT 404 NotFound No result in the user's collection
Collection errors COLLECTION_CONCURRENT_UPDATE 409 Conflict Concurrent update of the collection.
Collection errors COLLECTION_INVALID_RESPONSE 502 BadGateway Invalid response from the user's collection
Collection errors COLLECTION_OPERATION_UNKNOWN_ERROR 502 BadGateway The operation failed
Discovery errors DISCOVERY_INVALID_DATA 200 OK Error while reading new releases or spotlight data, some results may be missing or incomplete
Discovery errors DISCOVERY_NO_RESULT 404 NotFound No result from Discovery (New Releases and Spotlight)
Discovery errors DISCOVERY_INVALID_GENRE 404 NotFound No result from Discovery (New Releases and Spotlight), you might want to check if genre is well formatted
Discovery errors DISCOVERY_INVALID_RESPONSE 502 BadGateway Invalid response from Discovery (New Releases and Spotlight)
Streaming errors DELIVERY_3RD_PARTY_CANNOT_STREAM_PURCHASES 403 Forbidden Purchases are not available for streaming through the Groove Developer APIs.
Streaming errors DELIVERY_UNAVAILABLE_CONTENT 404 NotFound Content is not available for streaming
Streaming errors DELIVERY_ERROR 404 NotFound Unknown error when trying to stream content
Streaming errors DELIVERY_CONCURRENT_STREAMING 409 Conflict The user is already streaming on another device
Streaming errors DELIVERY_INVALID_RESPONSE 502 BadGateway Invalid response when trying to stream content
Subscription errors SUBSCRIPTION_INVALID_RESPONSE 502 BadGateway Invalid response when trying to get user's subscription
Server errors TOO_MANY_REQUESTS 429 TooManyRequests Too Many Requests
Server errors INTERNAL_SERVER_ERROR 500 Internal Server Error Oops, something went seriously wrong.

Sample JSON syntax

   "ErrorCode": "CATALOG_NO_RESULT",
   "Description": "Item does not exist"


Groove Service REST Reference