HTTP 503 error code collision - how to handle?

Hi everybody!

I just stumbled upon the new section on error codes and handling introduced with v1.12.3, which states HTTP 503 as an indication for “Another request already running on the device”.

This obviously collides with the same 503 code on /lockState, /lockAction and /lock. Semantically there is a big difference between the Nuki beeing offline or just busy for a moment. How do you expect the API client to handle this?

Best regards

Thanks for the request: The documentation could be missleading here, I agree!
If the device is just “offline” in the classical sense (e.g. test it out by removing the batteries of a connected device and send a /lockState for its ID) you will get back:
{"success": false}

I will update the documentation with 503 - hopefully - better explained as “unavailable/busy” in that cases (to distinguish between “not reachable” and “rechable, but can not process request”)

But the handling will still be similar for you: In the case of 503 a retry should be scheduled. And in the case of {“success”: false} you should also go for a retry first!
The difference would be the consequence of the same errors on repeated tries:
If it is constantly 503 something may be blocking a proper BLE communication; the integration and other user scenarios have to be checked.
If it is constantly {“success”: false}, the lock device itself needs to be checked for battery or mechanical issues.

(And I will also add this explanation to the FAQ part in the docs)

EDIT: The docs also seems to be missing the possible 410 error (for a device being noticed by the bridge as offline for longer time).
In this case you should immediatly check the device - a retry could still be done, but will most likely fail anyway.
Will also add this now!

1 Like

Thank you for adding the missing pieces!

Hello, I face the same issue of HTTP 503 but want to have queue instead of just leaving this problem as it is.

I have one Bridge with 2 devices: the nuki smart lock and the nuki opener
My use case is to use the opener to open my front door first and secondly use the smart lock to open my home door:*********&action=3

The problem is that the opener stays in a busy state and no other command can be sent within about 20 seconds. I always get the HTTP 503 code. So what happens:

We live in ground floor so we open the front door and waiting 20 seconds in front of our home door to let it open.
We programed a remote control to send both commands via http.

When we go to the garden we are not far away for automatically open any of both devices. so we need a better way to open both doors without using our smartphones (unlock, open app, tap on opener, waiting, tap on door).

So a queue of requested commands would be great.

You could try to use the “nowait” option mentioned in the documentation:


Hello, I tried to use nowait for both commands. But it is not working. I still get the same HTTP 503 error every single time I try one command while the other is still running.

The response from the nuki opener takes some time. So in that time I can not start the door command…

That is the definition of Error 503. The bridge can only handle one command at a time.

1 Like

So the solution is to live with that?
I could buy a new nuki opener with integrated bridge and use a 2nd bridge for the opener…
That is shit!

Is there no way to make it work?

You have to serialize your api calls as stated in the api faq and you should retry calls a given number of tries when still receiving 503. Thats how it can be handled very good.