Error Handling

error handling how litmus apis report errors and what to do about them rest http status codes standard codes, used as you'd expect code meaning common cause 200 / 201 success 204 no content delete returned successfully 400 validation error bad body, missing required field 401 unauthorized token expired, wrong client id/secret, wrong header for lem 403 forbidden token is valid but the user / client lacks permission 404 not found wrong path prefix or unknown resource id 409 conflict resumable upload session already open (run delete first) 5xx server error check edge / lem logs error body shape { "error" "\<short code>", "message" "\<human readable>" } graphql 200 with errors array graphql endpoints ( /devicehub/v2 , /digitaltwins/v2 , /cc/v2 , /opcua/v2 , /mqtt/gql ) return http 200 even on failure errors live in the body { "data" null, "errors" \[ { "message" "driver not found 12345", "path" \["createdevice"], "extensions" { "code" "not found" } } ] } always check body errors before reading body data a non null errors array means the operation failed even though the http status is 200 some graphql responses return partial data alongside errors (e g one entry in a list failed) the contract is data is what succeeded; errors lists what didn't lem async task per subtask status lem async task subtasks each carry a status status meaning pending queued, not started in progress running success done ok failed done with error; check errormessage field a parent task can have some subtasks succeed and some fail inspect each subtask, don't aggregate common 401 traps product header wrong header symptom le authorization bearer \<token> 401 with "invalid token" lem /api/v1/ x authtoken \<token> 401 using bearer returns "missing token" lem /admin/v1/ x authtoken \<token> same as above lem /mpcs/ authorization \<token> (no bearer prefix) 401 if you add bearer or use x authtoken luns authorization bearer \<token> (keycloak token) 401 if you use the le token instead of the uns issued one retries idempotent ops (get, put, delete on a specific id) safe to retry on 5xx and timeout post createx not safe to retry blindly may create duplicates either retry with a client side deduplication key or verify the resource via list before retrying async task launch 5xx during step 3 = retry safe (no taskid returned) 5xx during polling = retry safe resumable uploads if step 2 (put bytes) fails, run step 0 (delete) and start over the partial bytes are discarded