GlobalError

Players use the globalError object type for command responses that include generic errors that apply to commands in all namespaces in the Control API. Players send an errorCode and reason in the body, as well as a success value of false in the response header. The errorCode values are listed and described below.

The reason values are readable strings that describe syntax and parameter errors. These strings are not intended for end-user display or for use programmatically. If your app receives one of these error responses, you may be able to debug the error as described below.

🚧

The ERROR_INVALID_PARAMETER error also includes a playerIds array in the body to share invalid player IDs in group commands. You should code your integration to ignore unexpected keys in case we add more in the future.

ERROR_MISSING_PARAMETERS

If your app does not send a required parameter in the header or body, the player responds with this error. For example, if your app sends a setVolume command in the groupVolume namespace, the player expects the target ID parameters householdId and groupId to be present in the command header (see Control for details about target ID parameters). If your setVolume command was missing a householdId in the header, your app would receive this error:

{
  "errorCode": "ERROR_MISSING_PARAMETERS",
  "reason": "Missing required value:[0].householdId"
}

If your app sent the proper target ID parameters in the header, but did not send the volume parameter, the player would send this error:

{
  "errorCode": "ERROR_MISSING_PARAMETERS",
  "reason": "Missing required value:[1].volume"
}

ERROR_INVALID_SYNTAX

If your app sends a malformed JSON command to the player, the player responds with an ERROR_INVALID_SYNTAX in the target namespace:

{
  "errorCode":"ERROR_INVALID_SYNTAX"
}

ERROR_UNSUPPORTED_NAMESPACE

When your app sends a namespace that is not recognized by the player, you'll receive an ERROR_UNSUPPORTED_NAMESPACE error response. Note that namespaces are case-sensitive.

For example, if you misspelled the namespace, the player responds with an ERROR_UNSUPPORTED_NAMESPACE in the global namespace:

{
  "errorCode": "ERROR_UNSUPPORTED_NAMESPACE"
}

ERROR_UNSUPPORTED_COMMAND

When your app sends a command that is not recognized by the player, you'll receive an ERROR_UNSUPPORTED_COMMAND error response for the target namespace and householdId. Note that commands are case-sensitive.

{
  "errorCode": "ERROR_UNSUPPORTED_COMMAND"
}

ERROR_INVALID_PARAMETER

If your app provides an invalid parameter, it will receive an ERROR_INVALID_PARAMETER from the player.

For example, if your app sends a setVolume command with a volume outside the valid range, such as -1 when the range is 0 to 100:

{
  "volume": -1
}

The player will respond with this error:

{
  "errorCode": "ERROR_INVALID_PARAMETER"
}

If your app sends invalid player IDs in the createGroup or setGroupMembers commands, or the modifyGroupMembers command to add players to the group, the player responds with:

{
   "errorCode":"ERROR_INVALID_PARAMETER",
   "reason":"Set of players to group (array playerIds) contains invalid player ids",
   "playerIds":[
      "invalid_player_id0",
      "invalid_player_id1",
      "invalid_player_id2"
   ]
}

ERROR_INVALID_OBJECT_ID

In certain cases your app is required to provide a matching object identifier for the command to be executed. When your app fails to provide the correct object identifier, it will receive an ERROR_INVALID_OBJECT_ID error.

For example, the seek command in the playbackSession namespace requires that your app provides the itemId of the current item. If your app sends a seek command with an itemId that is not the currently playing or paused item in the cloud queue, it will receive this response:

{
  "errorCode": "ERROR_INVALID_OBJECT_ID"
}

ERROR_COMMAND_FAILED

An ERROR_COMMAND_FAILED indicates an internal player error. For example, if your app sends a setVolume command to set the volume to 20 on a CONNECT player that has been configured to have a fixed line-out setting, the player will send this response to your app:

{
  "errorCode": "ERROR_COMMAND_FAILED"
}

ERROR_NOT_CAPABLE

An ERROR_NOT_CAPABLE indicates that the targeted speaker does not support the command. For example, if your app sends a loadLineIn command to a player that does not support line in, such as a Sonos One. The player will send this response to your app:

{
    "errorCode": "ERROR_NOT_CAPABLE"
}