Key takeaways
- Plan for about three requests per second per connection, and pace writes through a queue.
- Split text over 2,000 characters and lists over 100 items, and send big pages in chunks.
- Buttons cannot be pressed through the API, and connections only see what is shared with them.
- Look up before you create to prevent duplicates.
- Check plan limits when content stops appearing.
Notion is a pleasant place to keep a CRM, a content calendar or an order log, and the API makes it tempting to automate. Then a sync that worked for twenty records starts failing at two hundred, a long text field is cut off, or a page refuses to update. These are not bugs. They are limits, and you can design for every one of them.
This guide lists the limits that most often break Notion automations, explains what each looks like in practice, and gives the design change that avoids it.
The request rate: about three per second
Notion allows an average of around three requests per second per connection, with some room for bursts. When you exceed it, the API answers with a rate-limited error and tells you how long to wait. An automation that loops over a database and updates each page in turn will hit this wall quickly.
- Queue your calls so they run at a steady pace below the limit.
- Respect the wait time in the response, then retry, instead of retrying immediately.
- Batch the logic, not the calls. Notion has no bulk-update endpoint, so reduce the number of pages you touch by updating only what changed.
- Use more than one connection only if it is allowed by your design, not as a way around the limit.
Size limits that cut content off
| Limit | What it means in practice |
|---|---|
| Rich text: 2,000 characters per text object | A long note or description must be split across several text objects, or it is rejected. |
| Arrays: 100 elements | A request that sends more than 100 items in a list, such as multi-select values or children, is refused. |
| Request size: 1,000 blocks and about 500 KB | Creating a long page in one call fails. Send it in chunks. |
| Pagination: up to 100 results per page | Reading a big database means following a cursor through many pages. |
None of these are hard to handle once you know them, but each one fails silently if your code does not check. A description that was truncated to 2,000 characters looks fine in the log.
What an automation cannot do
- Press a Button. Button blocks and button properties are meant for people. The API cannot press them, so an automation that depends on one needs a different trigger.
- See what has not been shared. A connection can only read and write pages and databases that were explicitly shared with it. A permission error is often a sharing problem.
- Ignore plan limits. On the free plan, a workspace with several members has a cap of 1,000 blocks, and content created through connections counts toward it.
If an automation seems to stop creating content for no reason, check the workspace’s plan and block count before you debug the code.
Webhooks: verify and expect retries
Notion can notify your endpoint when content changes. Verify the signature header on every request before you trust it, answer quickly, and expect that a delivery may be retried if you fail to answer. As with any webhook, record what you have already handled and fetch the page’s current state before acting.
Property types that trip people up
- Relations and rollups are computed or linked values. Write to the relation, read the rollup, and do not try to write the rollup.
- Select and multi-select values that do not exist yet are created on write in many cases, which can silently add new options. Normalize values first.
- Dates and time zones are stored with or without a time zone depending on how they were created. Be explicit when you write them.
- Formulas are read-only through the API.
A reliable pattern
- Identify records by a stable key you control, such as an order number stored in a property.
- Look up before you create. Update when found; create only when not found.
- Send writes through a queue that paces requests and honors wait times.
- Split long text and long lists into chunks that fit the limits.
- Log every write with the page ID so you can audit later.
- Run a nightly comparison of the source system and the database, and fix differences.
The look-up-before-create rule alone prevents the most common Notion automation bug: duplicate pages from retries and re-runs.
A short checklist
- Requests paced below the average rate
- Wait time honored after a rate-limited response
- Long text split into 2,000-character objects
- Lists chunked to 100 items
- Pagination followed to the end
- Page shared with the connection
- Webhook signatures verified
- Look-up before create, always