Google智能家居Action错误响应正确用法咨询及示例请求

Hey there! The issue with your current response is likely the redundant top-level errorCode in the payload—this field is only intended for global failures that affect the entire request, not when individual commands encounter errors. Let’s break down the proper structure based on Google’s official guidelines.

Key Rules to Stick To #

• Always include the requestId to map the response back to the original request (you’ve got this part right!).
• For individual command errors: Each entry in the commands array needs status: "ERROR", the affected device ids, and an errorCode specific to that command’s failure.
• For global errors (the entire request couldn’t be processed at all): Add a top-level errorCode in the payload. You can optionally include the commands array with all entries marked as ERROR, but it’s often omitted if the request was completely unprocessable.

Example 1: Per-Command Auth Expiry Error #

If only one device’s command failed due to expired authentication, your response should look like this:

{
  "requestId": "13711695294173375391",
  "payload": {
    "commands": [
      {
        "status": "ERROR",
        "ids": ["5a1cbc26e4b0532d095e72a0"],
        "errorCode": "authExpired",
        "debugString": "Authentication token for device 5a1cbc26e4b0532d095e72a0 has expired" // Optional, for internal debugging
      }
    ]
  }
}

We removed the top-level errorCode here because this is a per-device failure, not a global issue affecting all commands.

Example 2: Global Auth Expiry Error #

If the entire request failed because the user’s authentication token is expired (e.g., invalid for all devices), use a top-level errorCode:

{
  "requestId": "13711695294173375391",
  "payload": {
    "errorCode": "authExpired",
    "debugString": "User's authentication token has expired. Please prompt them to re-authenticate." // Optional
  }
}

In this case, you can omit the commands array entirely since no commands were processed.

Example 3: Mixed Success and Error Responses #

If some commands succeeded and others failed, each command gets its own status and error details:

{
  "requestId": "13711695294173375391",
  "payload": {
    "commands": [
      {
        "status": "SUCCESS",
        "ids": ["device_abc123"]
      },
      {
        "status": "ERROR",
        "ids": ["5a1cbc26e4b0532d095e72a0"],
        "errorCode": "authExpired"
      }
    ]
  }
}

Quick Tips #

• Use Google’s predefined error codes (like authExpired, deviceOffline, invalidRequest) instead of custom ones whenever possible—these align with Google’s expected response schema.
• The debugString field is optional and meant for your internal debugging; it won’t be displayed to end users.

内容的提问来源于stack exchange，提问作者eric zhao