mailchimp API error: page parameter must be a positive integer
Fixes Mailchimp integrations that fail with 'page parameter must be a positive integer'. Use when the Mailchimp API rejects your list request with this exact page-parameter error. Not for bad API keys, not for invalid list ids, not for pagination errors on other providers.
TL;DR
Send page as a plain integer starting at 1. The error means your code passed 0, a negative number, a decimal, or a non-numeric string as the page. Default it to 1 and coerce it to an integer before the request.
mailchimp API error: page parameter must be a positive integerSteps
- Log the exact page value your client sends on the failing request. Expected: you see the offending value (often 0, an empty string, or a float).
- Find where the page number is built: check for off-by-one loops starting at 0, string concatenation, or values pulled from user input. Expected: you locate the code that produces the bad value.
- Coerce the value to an integer and clamp it to a minimum of 1 before sending. Expected: the outgoing request always carries page as 1 or higher.
- Re-run the request. Expected: Mailchimp accepts the page parameter and returns the list data.
- If you paginate, confirm the loop increments from 1 and stops when the response has no more items. Expected: a full walk completes with no page errors.
Use this when
- Mailchimp returns exactly "page parameter must be a positive integer".
- A generated client numbers pages from 0 like an array index.
- The page value comes from user input or a config and is not validated.
Not for this skill when
- The API key is wrong (that fails authentication, not the page check).
- The list or audience id is invalid (that error names the resource).
- Another provider rejects your page parameter with different wording.
Variant phrasings
- Mailchimp page must be positive integer
- Mailchimp invalid page parameter error
- Mailchimp pagination page parameter error
Why it happens
Mailchimp pages start at 1, but generated clients habitually start loops at 0, pass through empty strings from unset config, or forward raw user input. The API validates the parameter strictly, so anything that is not a positive whole number is rejected before the query runs.
Edge cases
- An empty-string page from an unset variable fails the same check; default it, do not just coerce it.
- Mailchimp also caps how far you can page with offset style; for very large lists prefer the API's cursor-style options where offered.
- Count and page interact: a huge count with a high page can still return empty results without error, which is normal, not a bug.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstIzBwrAZ5TQ3oHS9r4l54g