Response handling

The iot/v1 API uses HTTP status codes for transport-level outcomes and stable JSON fields for application-level handling.

Feed-data ingestion responses expose a top-level status on success and an error object on failure. Device catalog responses expose a top-level code and a resource array named commands or sensors. Treat catalog code values as catalog response metadata only; feed-data ingestion is handled through HTTP status plus status or error.type.

HTTP status summary

HTTP status	Meaning	Typical response body
200	Request succeeded.	`status` for idempotent or batch feed-data responses; `code` and catalog arrays for command/sensor catalog responses.
201	One feed-data item was created.	`status`, `feed_data_id`, `message_id`, and `warnings`.
401	The request is not authenticated.	`error.type` is `unauthorized` for missing Bearer credentials or `invalid_token` for malformed, unknown, expired, or revoked Bearer access tokens.
402	The control-device subscription is not active.	`error.type` is `subscription_inactive`.
403	The token is not authorized for the requested device or scope.	`error.type` is `forbidden` for cross-device access or `insufficient_scope` when the Bearer access token lacks the required OAuth scope.
404	The requested device, command, or sensor was not found.	`error.type` is `resource_not_found`.
409	The submitted message conflicts with an existing message id.	`error.type` is `message_conflict`.
413	The request body exceeds the device plan byte budget.	`error.type` is `payload_too_large`.
415	The feed-data request body is not JSON.	`error.type` is `unsupported_media_type`.
422	The request body is syntactically valid but semantically invalid.	`error.type` is `validation_failed`.
429	The request cadence exceeds the plan rate limit.	`error.type` is `rate_limited`.

Feed-data success

A single accepted item returns 201 Created.


          {
            "status": "created",
            "feed_data_id": 123,
            "message_id": "iot-message-1",
            "warnings": []
          }

Device catalog success

Catalog endpoints return 200 OK with the catalog array requested by the device.


          {
            "code": 2000,
            "commands": [
              {
                "id": 1,
                "value": "0.0",
                "value_type": "NumericRange",
                "kind": "relay",
                "pin_port": "6"
              }
            ]
          }

Error response

Error responses include a stable string identifier and request id.


          {
            "error": {
              "type": "validation_failed",
              "message": "feed data ingestion failed",
              "details": {
                "command_id": ["is invalid for this device"]
              }
            },
            "request_id": "..."
          }

Device handling rules

Check the HTTP status code first.
For feed-data success, inspect top-level status values such as created, idempotent, or processed.
For catalog success, inspect top-level code and then the requested commands or sensors array.
For errors, inspect error.type and use error.details for field-level diagnostics. Do not depend on numeric catalog codes for feed-data errors.