409 Conflict error from Machines API

Hi there!

We’re seeing some 409 Conflict errors when using the Update Machine API endpoint. Unfortunately, I’m unable to get the specific error message from production (we don’t log them to avoid logging potentially sensitive customer information) and have been unable to reproduce it locally. Are there any general reasons why this might happen? We’d like to catch this error and raise a user-friendly message to our users if possible. Our basic flow is to get a list of machines, iterate through them fetching their config, then posting the same config we got back from the API to trigger a restart. Are there any obvious things that would cause this?

Also, are there any other well-known errors from the API that we might want to handle as well? As an example, we just added in handling for the 422 that gets returned if you hit your machines limit for the account when attempting to scale past it.


There’s a few cases where a 409 Conflict can be returned:

  • there’s a lease on the machine and it was not provided in the update request docs
  • if current_version was provided in the request body does not match the current version of the machine (which is presented as the instance_id as a response to the Get and List machines endpoints
  • there are not enough resource capacity on the host to perform the update (can happen when scaling memory/CPU up)

There other 4xx status code users may see is 400 (Bad Request) which should contain enough information in the error response and 412 (Precondition Failed) which can only happen if the machine attempts to use a volume that’s already in use by another machine.

We’ve only just recently published an swagger/OpenAPI spec and are continuing to update it to provide the details like status codes and potential error messages.

@JP_Phillips Awesome, thanks! Will all 409 responses use this payload format?

{ "status":"error", "message":"machine ID 3d8d413b29d089 lease currently held by hello@fly.io, expires at 2022-10-20 19:59:06 +0000 UTC", "code":"invalid" }

The response we saw from a 422 was more like this:

{ "error": "To create more than 50 machines per organization please contact billing@fly.io" }

Will these eventually all use the same payload format?


It is an unfortunate oversight on our part when we added the lease endpoints that they used a different format from the rest of the endpoints. All error responses should be of the form:

  "error": "string",
  "details": "string", // optional
  "status": "string", // optional

aside from the lease endpoints which are:

  "status": "success|error",
  "message": "string",
  "code": "invalid|not_found",

Great, thanks!

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.