400 Bad Request when maxResults exceeds limit in Jira Align API

Answer

When you send a request to a Jira Align endpoint with maxResults set above the value that the endpoint’s documentation lists as the maximum, the server responds with a 400 Bad Request. The 400 status is not a “generic” error; the response body contains a message such as maxResults must be <= 100 or a similar range‑check error. This is a hard limit enforced by the API, not a configurable setting.

Likely Explanation

Jira Align implements a per‑endpoint ceiling for maxResults to protect the underlying database and service layer from large, potentially expensive queries. The default value is often 50, but the maximum is typically 100 for most endpoints. Some newer releases or specific resources (e.g., /epic vs. /userStory) may allow up to 200 or 500, but the limit is still fixed in the API definition.

Confirmed Facts

• Each endpoint’s reference page lists an explicit maximum for maxResults.
• Exceeding that maximum results in a 400 status and a clear error message.
• The API does not expose a way to raise the limit via tenant configuration.
• Most endpoints do not return a Link header for pagination; instead, you must use the startAt (or equivalent) query parameter to request subsequent pages.

Resolution Steps

1. Check the Documentation
   Navigate to the endpoint’s page in the Jira Align API reference and note the maxResults ceiling.
2. Adjust the Request
   Set maxResults to the documented maximum (e.g., 100). Example:

   curl -X GET \
     "https://your‑tenant.align.apps.atlassian.com/api/v1/epic?startAt=0&maxResults=100" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json"
   

3. Paginate for Larger Result Sets
   When you need more items than the maximum, repeat the call with an updated startAt value:

   for start in 0 100 200 ...; do
     curl ... "?startAt=$start&maxResults=100"
     # process response
   done
   

4. Validate the Response
   Verify that the HTTP status is 200 and that the total field (if present) indicates the full dataset size.
5. Handle Errors Gracefully
   If you receive a 400, parse the body to confirm it mentions maxResults out of range. Log the error and adjust the parameter accordingly.

Is There a Dynamic Increase?

No. Jira Align does not provide a tenant‑level setting to raise the hard cap. The only way to retrieve more than the maximum per page is to paginate using startAt.

Link Header Support?

Unlike some REST APIs, Jira Align does not include a Link header for pagination. All navigation must be handled client‑side via the query parameters.

Diagnostic Question

Which specific endpoint are you calling, and what is the maximum maxResults value documented for that endpoint? Knowing this can confirm whether you’re hitting the correct ceiling or if another parameter is causing the 400.