{"__v":4,"_id":"55f28173f9f3991900f38a19","category":{"__v":1,"_id":"55f28172f9f3991900f38a15","pages":["55f28173f9f3991900f38a17","55f28173f9f3991900f38a18","55f28173f9f3991900f38a19","55f28173f9f3991900f38a1a","55f28173f9f3991900f38a1b","55f28173f9f3991900f38a1c"],"project":"54ebb40d6423300d003672c0","version":"55f28172f9f3991900f38a13","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-17T04:27:26.544Z","from_sync":false,"order":1,"slug":"overview","title":"Overview"},"project":"54ebb40d6423300d003672c0","user":"557e2561eb75d80d00af3dab","version":{"__v":2,"_id":"55f28172f9f3991900f38a13","project":"54ebb40d6423300d003672c0","createdAt":"2015-09-11T07:23:30.065Z","releaseDate":"2015-09-11T07:23:30.065Z","categories":["55f28172f9f3991900f38a14","55f28172f9f3991900f38a15","55f28172f9f3991900f38a16","55f66acb297b37170058accb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T04:52:11.610Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Clients are expected to handle errors and should use the response status code and body to determine the cause of the error.\n\nThe LIFX HTTP API uses conventional status codes where possible, but not all status codes map cleanly to physical lights. Generally 4xx status codes indicate a problem with the client and 5xx status codes indicate a problem with LIFX servers. Where possible, a message is included in the response explaining the corrective action.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Codes\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status\",\n    \"h-1\": \"Reason\",\n    \"0-0\": \"`200 OK`\",\n    \"0-1\": \"Everything worked as expected\",\n    \"1-0\": \"`207 Multi-Status`\",\n    \"1-1\": \"Inspect the response body to check status on individual operations.\",\n    \"3-0\": \"`401 Unauthorized`\",\n    \"3-1\": \"Bad access token.\",\n    \"5-0\": \"`404 Not Found`\",\n    \"5-1\": \"Selector did not match any lights.\",\n    \"6-0\": \"`422 Unprocessable Entity`\",\n    \"6-1\": \"Missing or malformed parameters.\",\n    \"8-0\": \"`429 Too Many Requests`\",\n    \"8-1\": \"The request exceeded a rate limit. See the [Rate Limits](doc:rate-limits) section.\",\n    \"9-0\": \"`500, 502, 503, 523 Server Error`\",\n    \"9-1\": \"Something went wrong on LIFX's end.\",\n    \"7-0\": \"`426 Upgrade Required`\",\n    \"7-1\": \"HTTP was used to make the request instead of HTTPS. Repeat the request using HTTPS instead. See the [Authentication](doc:authentication) section.\",\n    \"2-0\": \"`400 Bad Request`\",\n    \"2-1\": \"Request was invalid.\",\n    \"4-0\": \"`403 Permission Denied`\",\n    \"4-1\": \"Bad OAuth scope.\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example Error Response\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"color is missing\\\",\\n  \\\"errors\\\": [\\n    {\\n      \\\"field\\\": \\\"color\\\",\\n      \\\"message\\\": [\\\"is missing\\\"]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Warnings\"\n}\n[/block]\nWarnings indicate that there was an issue with the request, but the request did succeed. For example, if you supply extraneous arguments to a request, the response hash will contain a `warnings` array.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// foo=bar was supplied to a PUT /state request\\n{\\n    \\\"results\\\": [\\n        {\\n            \\\"id\\\": \\\"d073d5115931\\\",\\n            \\\"label\\\": \\\"Lamp\\\",\\n            \\\"status\\\": \\\"ok\\\"\\n        }\\n    ],\\n    \\\"warnings\\\": [\\n        {\\n            \\\"unknown_params\\\": {\\n                \\\"foo\\\": \\\"bar\\\"\\n            },\\n            \\\"warning\\\": \\\"Unknown params\\\"\\n        }\\n    ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"warning.json\"\n    }\n  ]\n}\n[/block]","excerpt":"Handling things when they don't go right","slug":"errors","type":"basic","title":"Errors and Warnings"}

Errors and Warnings

Handling things when they don't go right

Clients are expected to handle errors and should use the response status code and body to determine the cause of the error. The LIFX HTTP API uses conventional status codes where possible, but not all status codes map cleanly to physical lights. Generally 4xx status codes indicate a problem with the client and 5xx status codes indicate a problem with LIFX servers. Where possible, a message is included in the response explaining the corrective action. [block:api-header] { "type": "basic", "title": "Response Codes" } [/block] [block:parameters] { "data": { "h-0": "Status", "h-1": "Reason", "0-0": "`200 OK`", "0-1": "Everything worked as expected", "1-0": "`207 Multi-Status`", "1-1": "Inspect the response body to check status on individual operations.", "3-0": "`401 Unauthorized`", "3-1": "Bad access token.", "5-0": "`404 Not Found`", "5-1": "Selector did not match any lights.", "6-0": "`422 Unprocessable Entity`", "6-1": "Missing or malformed parameters.", "8-0": "`429 Too Many Requests`", "8-1": "The request exceeded a rate limit. See the [Rate Limits](doc:rate-limits) section.", "9-0": "`500, 502, 503, 523 Server Error`", "9-1": "Something went wrong on LIFX's end.", "7-0": "`426 Upgrade Required`", "7-1": "HTTP was used to make the request instead of HTTPS. Repeat the request using HTTPS instead. See the [Authentication](doc:authentication) section.", "2-0": "`400 Bad Request`", "2-1": "Request was invalid.", "4-0": "`403 Permission Denied`", "4-1": "Bad OAuth scope." }, "cols": 2, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Example Error Response" } [/block] [block:code] { "codes": [ { "code": "{\n \"error\": \"color is missing\",\n \"errors\": [\n {\n \"field\": \"color\",\n \"message\": [\"is missing\"]\n }\n ]\n}", "language": "json", "name": null } ] } [/block] [block:api-header] { "type": "basic", "title": "Warnings" } [/block] Warnings indicate that there was an issue with the request, but the request did succeed. For example, if you supply extraneous arguments to a request, the response hash will contain a `warnings` array. [block:code] { "codes": [ { "code": "// foo=bar was supplied to a PUT /state request\n{\n \"results\": [\n {\n \"id\": \"d073d5115931\",\n \"label\": \"Lamp\",\n \"status\": \"ok\"\n }\n ],\n \"warnings\": [\n {\n \"unknown_params\": {\n \"foo\": \"bar\"\n },\n \"warning\": \"Unknown params\"\n }\n ]\n}", "language": "json", "name": "warning.json" } ] } [/block]