Errors

Successful Cloud API responses use { "data": … } or { "data": […], "meta": … } — see API reference. Errors are not wrapped in data. Failed requests return JSON:

{
  "error": {
    "code": "bad_request",
    "message": "Human-readable explanation"
  }
}

Some validation errors include structured details (logged server-side; when returned, e.g. SICAR document preflight):

{
  "error": {
    "code": "bad_request",
    "message": "Document validation failed",
    "details": {
      "issues": [
        {
          "field": "lines[].art_id",
          "id": 999,
          "message": "art_id 999 not found or inactive in articulo"
        }
      ]
    }
  }
}

Depending on the error middleware path, details may be omitted from the HTTP body even when set on the server error. Prefer relying on code + message; treat details as best-effort when present.

Common codes

HTTP	`code`	Meaning
400	`bad_request`	Validation / bad input
401	`unauthorized`	Missing/invalid API key
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource missing (or hidden for enumeration)
409	`conflict`	State conflict (e.g. delete customer with active licenses/devices; revoke license while `pending`/`enrolled` devices remain — see `details.device_id` / `details.device_ids`)
429	`rate_limited`	Too many requests — see Rate limits
500	`internal_error`	Unexpected failure

Device / Gateway failures

Function invoke may return HTTP 200 with an agent error inside data.result:

{
  "data": {
    "device_id": "…",
    "function_id": "sicarv4.products.search",
    "operation": "db.query",
    "result": {
      "status": "error",
      "error": { "code": "…", "message": "…" }
    }
  }
}

Always check data.result.status / data.result.error for device-side failures (offline, SQL error, timeout).