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

Status

Reason

200 OK

Everything worked as expected

202 Accepted

For endpoints supporting Fast Mode the request was accepted.

207 Multi-Status

Inspect the response body to check status on individual operations.

400 Bad Request

Request was invalid.

401 Unauthorized

Bad access token.

403 Permission Denied

Bad OAuth scope.

404 Not Found

Selector did not match any lights.

422 Unprocessable Entity

Missing or malformed parameters.

426 Upgrade Required

HTTP was used to make the request instead of HTTPS. Repeat the request using HTTPS instead. See the Authentication section.

429 Too Many Requests

The request exceeded a rate limit. See the Rate Limits section.

500, 502, 503, 523 Server Error

Something 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"
        }
    ]
}