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.

Response Codes

StatusReason
200 OKEverything worked as expected
202 AcceptedFor endpoints supporting Fast Mode the request was accepted.
207 Multi-StatusInspect the response body to check status on individual operations.
400 Bad RequestRequest was invalid.
401 UnauthorizedBad access token.
403 Permission DeniedBad OAuth scope.
404 Not FoundSelector did not match any lights.
422 Unprocessable EntityMissing or malformed parameters.
426 Upgrade RequiredHTTP was used to make the request instead of HTTPS. Repeat the request using HTTPS instead. See the Authentication section.
429 Too Many RequestsThe request exceeded a rate limit. See the Rate Limits section.
500, 502, 503, 523 Server ErrorSomething went wrong on LIFX's end.

Example Error Response

{
  "error": "color is missing",
  "errors": [
    {
      "field": "color",
      "message": ["is missing"]
    }
  ]
}

Warnings

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.

// foo=bar was supplied to a PUT /state request
{
    "results": [
        {
            "id": "d073d5115931",
            "label": "Lamp",
            "status": "ok"
        }
    ],
    "warnings": [
        {
            "unknown_params": {
                "foo": "bar"
            },
            "warning": "Unknown params"
        }
    ]
}