504 Timeout Errors

When sending an invoice to Freeagent via the api to /v2/invoices we’ve recently started receiving the following response:

<head><title>504 Gateway Time-out</title></head>
<center><h1>504 Gateway Time-out</h1></center>

This does not happen every time, and repeating exactly the same request can result in it successfully going through.
This seemed to start happening around 24th February 2023 and we’ve seen this error a few times each week since.

Like I say it’s really not consistent, we’ve not made any changes to our codebase recently, so I think the actual request is fine.

Really not sure what to try next or how to debug any further. Any help much appreciated!

Hi Tom :wave:

Thank you for getting in touch about this! We’re happy to take a look into this to see why you’re seeing the timeout message.

Would you be able to let me know the subdomain of the company you are trying to create invoices on?


Hi Katie,

I’m Tom’s colleague.

It’s mcircle.freeagent.com



Hi Bruno & Tom,

Thanks for getting back to me!

We’ve been able to take a look into why you’ve been seeing 504 timeout issues. We’ve found that our network gateway had a shorter wait period than the app itself. The gateway would only wait for 1 minute, while the app would wait for 5. We can see that the requests that you have been sending have lasted for around 65 seconds, which is just over the limit that the gateway would stay open for, but well within the app’s timeout. Therefore, these requests have generally succeeded, but unfortunately it was just a little too late for you to get the success message.

Because of this difference in the timeframes, our Ops team are looking at increasing the timeout on the gateway to match the app’s timeout of 5 minutes. Once this is done, you should no longer see this “504 Gateway Time-out” message (unless they start taking longer than 5 minutes to complete! :smile: )

We also had a look into why the requests were taking a long time to complete, and this is due to the large number of invoices in the account itself. Unfortunately, as the number of invoices increase on the account, these queries are going to run slower.

We are taking a look to see if there’s anything we can do to speed up this process on our side, but it may be that there’s not much that can be done to improve the process. But in any case, these requests should stop giving you that error message in the near future once this timeout has been updated.

I hope this helps! And thank you for bringing this to our attention.

Kind regards,

Hi Katie,
Sorry we didn’t reply sooner. I’ve set myself to “Watching” this thread to get future updates more quickly.

The timeout thing is a very useful insight. Thanks to the ops team for identifying that as the issue.

You mentioned “this is due to the large number of invoices in the account itself”… is the volume of invoices or the volume of contacts? We’ve got more contacts than invoices so I can imagine it’s actually the contacts volume being the greater issue.

What might speed up the request? If we sent the contact_id, would that help?

Can the ops team pinpoint where the pain is growing? Returning a list of invoices or returning a list of contacts on our account?

Finally, have they had the chance to increase the timeout on the gateway to match the app’s timeout of 5 minutes?

Kind regards,


Hi Bruno,

The slow request is happening due to the number of invoices in the account, and not to do with the contacts. The slow part of the request is when FreeAgent is generating the invoice reference, so this has no interaction with contacts at this point, and so passing in the contact_id won’t help to speed this up unfortunately.

I have opened up an issue report for the slow requests so that our engineering teams can take a look into how we are generating this invoice reference and see if there is anything we can do to speed the process up. Unfortunately I won’t be able to give you a timescale for when this might be looked into or improved, and I can’t guarantee that there will be a solution to this issue.

However, our ops team have let me know that they have now fixed the issue with the timeout, and so you should no longer be seeing 504 errors when posting invoices. Now that the timeout limit has increased by 5, you should hopefully not see any more issues for a long while!

Kind regards,

Thanks Katie. That’s helpful to know. Maybe an index of some kind? Or it’s looping over something unnecessarily.

Anyhow, at this end, to handle the potential time outs we’re now putting our requests into a queue and they’ll get retried up to 4 times by the queue. Hopefully it won’t even fail now that you’ve extended the timeout period.

Separately, we’re wanting to delete all the contacts who have no invoice or estimate or bill. Trying to export the contacts from the website times out.

Are you able to run anything for us to wipe all “empty” contacts? Or advise how we might do it?

Many thanks,