Errors

Failed requests return an HTTP error status and an error envelope.

Error format

{
  "success": false,
  "data": null,
  "error": {
    "code": 404,
    "reason": "invalid_device_credentials",
    "message": "Device does not exist or the safe code is incorrect."
  }
}

Field	Type	Description
code	integer	HTTP status code
reason	string | null	Machine-readable reason, when the endpoint provides one
message	string	Human-readable text. Field validation errors use field: message. Some messages follow Accept-Language.

Handle errors by HTTP status and reason. Show message to people, but do not parse it.

Generic errors

Authentication failed

The request has no credentials, or the token is invalid, expired, or inactive. The API returns 403 for these cases, not 401.

{
  "success": false,
  "data": null,
  "error": { "code": 403, "reason": null, "message": "Invalid token" }
}

Forbidden

The caller lacks the role for the endpoint, the resource is outside the token's project scope, or an API token called an Owner-only endpoint.

{
  "success": false,
  "data": null,
  "error": { "code": 403, "reason": null, "message": "You do not have permission to perform this action." }
}

Bad request

A parameter is missing or invalid. message names the first failing field.

{
  "success": false,
  "data": null,
  "error": { "code": 400, "reason": null, "message": "port must be an integer between 1 and 65535." }
}

Not found

The resource does not exist, or the caller cannot see it.

{
  "success": false,
  "data": null,
  "error": { "code": 404, "reason": null, "message": "Device not found." }
}

Method not allowed

The resource does not support the HTTP method, for example POST /projects/{project_id}/devices/.

Service unavailable

A dependency failed: the device gateway, the real-time data store, or the export service. Retry with exponential backoff.

Internal server error

An unexpected failure. Retry once; contact support if the error persists.

Plan errors

Status	Reason	Description
403	membership_readonly	The organization's plan is inactive. Read requests work; write requests fail. Point off and stop commands stay available.
403	membership_quota_exceeded	Creating or moving the resource would exceed the plan's project, device, or point quota.

Reason codes

Status	Reason	Endpoint	Description
400	device_already_assigned	Bind a device	The device is already in a project
400	device_owned_by_other_org	Bind a device	The device belongs to another organization
404	invalid_device_credentials	Bind a device	Wrong serial number or safe code
409	point_in_use	Delete a point	Other configuration still references the point
400	INVALID_DEVICE	Create an export task	device_id is missing or not a positive integer
400	INVALID_FACTORS	Create an export task	factors is missing or empty
403	INVALID_FACTORS	Create an export task	A point does not exist on the selected device
400	TOO_MANY_FACTORS	Create an export task	More points than the export limit
400	INVALID_TIME_RANGE	Create an export task	Missing time, or end_time before start_time
400	EXPORT_RANGE_TOO_LARGE	Create an export task	Range longer than the export limit
400	INVALID_FORMAT	Create an export task	format is not csv or json
400	INVALID_NAME	Create an export task	name is longer than 128 characters
400	INVALID_IDEMPOTENCY_KEY	Create an export task	Idempotency-Key is longer than 64 characters
404	DEVICE_NOT_FOUND	Create an export task	The device is not in the project
409	TASK_NOT_CANCELLABLE	Cancel an export task	The task has already finished
409	TASK_NOT_RETRYABLE	Retry an export task	Only failed tasks can be retried
409	TASK_NOT_DELETABLE	Delete an export task	The task is still running
409 / 404	EXPORT_FILE_MISSING	Get a download URL	The task has no file yet (409) or the file is gone (404)
410	EXPORT_FILE_EXPIRED	Get a download URL	The file passed its retention period
503	EXPORT_TEMPORARILY_UNAVAILABLE	Export tasks	The export service or file storage is unavailable