Question 1

Is there a limit on a mass payout run?

Accepted Answer

There is no batch-size limit, because halfin has no batch object. A mass payout is a fan-out over POST /api/v1/payouts — one call per recipient — so the size of a run is whatever your loop produces, from a handful to many thousands. The practical bound is your own pacing against the API's rate limits: issue calls at a steady rate and back off when rate-limited. Each line's idempotency_key makes a backed-off retry safe. Funding and operator approval, not a run-size cap, are the gates that actually decide whether a run settles.

Question 2

Do I need to split a large recipient file into smaller batches?

Accepted Answer

No. There is no batch endpoint to size your chunks against, so you never split a file to fit a batch limit. You loop over the whole list and call POST /api/v1/payouts once per line. What you do manage is request rate — pace the loop with bounded concurrency and exponential backoff so a large run completes reliably without tripping rate limits. Because each line is independent and idempotent, you can pause and resume the run at any point.

Question 3

What happens if I send requests too fast?

Accepted Answer

The API will rate-limit you, returning a signal to slow down rather than silently dropping work. The correct response is to back off — wait and retry the affected line, lengthening the wait on repeated pushback, ideally with jitter. Re-sending a line is safe because it carries its own idempotency_key, so a retry pays the recipient at most once. Pacing the run at a sustainable rate from the start avoids the rate-limit cascade entirely.

Is there a limit on a mass payout run?

Keep reading across the cluster.