Rate limits

Each API key can send 120 requests per minute. The count is shared between the REST API and MCP, and starts again at the top of every minute (UTC). Contractor sign-ins have their own allowance of 120 requests per minute for each company.

When you go over, Oatmilk answers 429 with a RATE_LIMITED error and a Retry-After header saying how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{ "error": { "code": "RATE_LIMITED", "message": "Too many API requests. Retry after the indicated delay." } }

Staying under the limit

• Wait for Retry-After, then retry with the same Idempotency-Key. Never retry in a tight loop.
• Use webhooks instead of polling. A webhook tells you the moment an invoice is paid, so you don't have to ask every few seconds.
• Filter on the server. One request with from, to and status is cheaper than many unfiltered pages.
• Spread background work. If a nightly job reads a lot, pace it rather than sending everything at once.

If your integration needs more, tell us what it does and we'll look at it with you.