- The
/api/v1list endpoints now limit the page size. A request with aper_pageabove the limit is rejected with a422error instead of being served. - Customer text fields now have a maximum length. Creating or updating a customer with a longer value is rejected with a
422error.
What are the changes?
A maximum page size on /api/v1
Every request on an /api/v1 path that sends per_page is checked before any data is read. When per_page is above the limit, it returns a 422 with the value_is_out_of_range code on per_page. A per_page equal to the limit is accepted.
A page or per_page that is not a positive number (0, a negative value, text) is not rejected. As before, it falls back to the first page or the default page size.
page or per_page, or send them empty, behave as before: the default page size stays 100.
The limit can be changed in two ways:
- For the whole instance, with the
LAGO_API_PAGINATION_MAX_PAGE_SIZEenvironment variable. - For one organization, with the new
pagination_max_page_sizecolumn of theorganizationstable. When it is set, it wins over the environment variable, higher or lower.
- The response of a valid request is unchanged.
- The GraphQL API used by the Lago front-end is not affected.
A maximum length on customer text fields
Creating or updating a customer now checks the length of its text fields, on the API, in the Lago app and in the customer portal:name already had a 255 character limit. A longer value returns a 422 with the value_is_too_long code on the field (the shipping fields are reported as shipping_city, shipping_address_line1 and so on):
invalid_characters code. The API and the Lago app still accept these characters.
Why are we doing this?
Until now, nothing limitedper_page on /api/v1. A single request such as GET /api/v1/invoices?per_page=1000000000 loaded the whole table in one response, and held a database connection and a worker for as long as it took. On a large instance, a few of these requests slowed the API down for every other client.
Customer text fields had no length limit either, and the customer portal let end customers write long, multi-line text into them. These values are shown on invoices and in the Lago app, and are read by the AI assistant. The limits keep them to the size of a real name or address.
What should self-hosted users do?
Cloud users do not need to follow steps 1 and 2. The Lago Team sets the page size limit for the organizations that need larger pages.
1. Check the page size your integrations send
Before upgrading, look for/api/v1 requests that send a per_page above 200 (in your API access logs, your load balancer logs, or the code of your integrations).
If none of them do, no action is needed: install v1.56.0 as usual.
2. Raise the limit before upgrading, if needed
If some integrations send aper_page above 200, choose one of the options below before installing v1.56.0. Otherwise these requests start failing with a 422 as soon as the new version runs.
Option A: raise the limit for the whole instance
Set the environment variable on the API container, then restart it:
The value is read on every request, so a later change only needs a restart, not a new release.
Option B: raise the limit for one organization
After installing v1.56.0 (the column is added by the database migrations), open a Rails console on your API server and set the limit of the organization:nil to use the instance limit again.
3. Check the customer values your integrations send
This step applies to Cloud and self-hosted users. Look for integrations that create or update customers with text longer than the limits above, for example a long legal name or an address sent in a single field. Shorten these values before sending them, or split an address acrossaddress_line1 and address_line2. Otherwise these requests fail with a 422 once v1.56.0 runs.