Limits, errors and safety
Rate limits and their headers, body size, the error shape and status codes, and what a key can never do.
- Rate limits follow the plan. The minute is per key or sign-in, the day is per account; a downgrade narrows them on the next request. Every answer carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(Unix seconds); a 429 addsRetry-Afterand names the plan in its message.Plan Keys A minute A day Free 1 20 200 Pro and Max 5 120 20,000 - Bodies are JSON objects up to 64 KB. Unknown fields are refused, by name, with a 400.
- Errors look like
{ "error": { "code": "not_found", "message": "…" } }, withdetails.issueswhen a field is wrong anddetails.planLimitwhen a plan limit was reached. - What a key cannot do: change your password or email, manage billing, make other keys, or reach anything the app itself does not let you reach. It is not for pages in a browser — there are no CORS headers, on purpose — keep it on a server or in a tool on your own machine.
- If a key leaks, revoke it in Settings → Integrations; the next request with it is a 401. We store only a hash of each key, so nobody can read it back, us included.
- A sign-in is a pair of tokens. The access token lasts an hour; the refresh token renews it for up to ninety days of use and is replaced every time it is used. Both count against the same rate limits as a key. Disconnect in Settings → Integrations → Connected apps ends both within one request; we store only hashes.
Status codes
| Status | Meaning |
|---|---|
| 200 / 201 | It worked; 201 when something was made. |
| 400 | The request could not be read — a missing field, a wrong type, a field we do not list. The message names it. |
| 401 | No credential, a malformed one, or a key or sign-in that was revoked. The answer names where to sign in. |
| 403 | The account may not do that (forbidden), or is at a plan limit (plan_limit). |
| 404 | Not yours, or gone. |
| 409 / 412 | A conflict — a saved note changed under you, or a key limit. |
| 413 | A body over 64 KB. |
| 422 | Readable, but not usable — Markdown that will not fit a note. |
| 429 | Over your plan’s rate limit; the message names the plan and its figures. Wait Retry-After seconds. |
| 500 / 503 | Our side. Try again in a moment. |