Response codes

Canonical HTTPS iot/v1 device responses include a numeric code for firmware-level handling. The response code is distinct from the HTTP status code: use HTTP status for transport handling, then use code for stable application behavior on the control device.

For HTTPS responses, top-level code is the response code. Error responses also expose readable fields for developers and tools. Successful feed-data responses include status. Error responses include error.type, error.message, error.details, and request_id. Treat error.type as the readable label for code, not as a second response-code system.

MQTT feed-data application acknowledgements use acknowledgement status, retryable, and optional error.type fields instead of numeric code. See the MQTT payload reference for those message shapes and field semantics for result-handling rationale.

On this page

Response code registry
Code Message Meaning Category error.type
2000 Ok Successful requests Success n/a
4000 Bad Request Invalid input, malformed request Client Error bad_request
4001 Unauthorized No valid authentication provided Client Error unauthorized
4002 Payment Required License or payment required Client Error payment_required
4003 Forbidden Access forbidden due to device policy Client Error forbidden
4004 Not Found Resource not found Client Error not_found
4009 Conflict Submitted message conflicts with existing device data Client Error conflict
4013 Request Entity Too Large Payload exceeds allowed size Client Error payload_too_large
4015 Unsupported Media Type Request media type is not supported Client Error unsupported_media_type
4022 Unprocessable Entity Semantic errors Client Error validation_failed
4029 Too Many Requests Rate limit exceeded Client Error rate_limited
5003 Service Unavailable Required device service is temporarily unavailable Server Error service_unavailable

Existing meanings are stable. Future API versions may add response codes, but they should not change the meaning of an existing code.

Payload examples

Concrete success payloads live with the endpoint or transport that returns them.

Error response

HTTPS error responses include a response code, a stable string identifier, structured details, and a request id for support. 


          {
            "code": 4000,
            "error": {
              "type": "bad_request",
              "message": "request is invalid",
              "details": {}
            },
            "request_id": "..."
          }

Schema: http-error-response.schema.json

Device handling rules
  • For HTTPS requests, check the HTTP status code first for transport-level success or failure.
  • For HTTPS responses, use top-level code for stable firmware behavior.
  • Use status values such as created, idempotent, and processed for successful feed-data outcomes.
  • For MQTT feed-data publishes, wait for the application acknowledgement and use status, retryable, and optional error.type from that acknowledgement.
  • Use error.type and error.details for readable diagnostics, logs, and developer tooling after the response code is handled.
  • Fallback to the HTTP status if a response from an older endpoint does not include code.