PolderAPI

Getting started

Rate limits and errors

How many requests you get, what each status code means and how to retry.

Rate limits

API Limit Counted per
Backlog 120 requests per minute Token
Docs 180 requests per minute, at most 10 per second Integration
Chat 60 requests per minute Token

Some endpoints that do something you cannot take back have a tighter limit of their own, shown in the endpoint bar: sending a mailing (6 a minute), sending a test mail (10), declaring an incident (30), sending a contract from Chat (10).

Over the limit you get 429 Too Many Requests with a Retry-After header. Wait that many seconds, then retry. Two tokens never share a bucket, so one noisy script does not slow another down.

Tip Use a separate token per integration. Then a 429 or a surprising call can be traced to one name in Settings → API tokens.

Status codes in the Backlog API

Status Meaning
200 Done. The payload is under data.
201 Created.
204 Done, nothing to return (deletes).
401 No token, or the token is wrong, revoked or expired.
403 The token lacks the scope, its owner may not do this, or an OAuth app was granted a different workspace.
404 It does not exist, or you may not see it. The two look the same on purpose.
422 The input did not validate.
429 Too many requests.

Error bodies are JSON with a message. Validation errors also list the fields:

{
  "message": "The title field is required.",
  "errors": { "title": ["The title field is required."] }
}

Handling errors well

  • Treat 429 and 5xx as retryable, with a growing delay. Do not retry 4xx other than 429.
  • A 403 on a write that worked yesterday usually means the owner lost a role or left a team.
  • A 404 on something you know exists means it is private to people your token's owner is not part of.

The Docs API

It answers every failure with Notion's error object (object, status, code, message, request_id). See Docs API.