Notion API · api · fg-0465
Retrying a Notion page create after a 502 or 503 leaves duplicate pages in the database
Request to Notion API failed with status: 502
Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100
Cause
Notion can save a write and still answer with a timeout, so a blind retry of POST or PATCH repeats it. Notion's guidance is to retry 5xx only for GET and DELETE unless the caller has its own idempotency check, and the JS SDK follows that rule.
Fix
Before retrying a create, query for the row by a unique property you set on it. On 503, read additional_data.retry_guidance before deciding.
Apply
const hit = await notion.dataSources.query({ data_source_id, filter: { property: "External ID", rich_text: { equals: extId } } });
if (hit.results.length === 0) await notion.pages.create(payload);Affects: Notion REST API and @notionhq/client 5.x retry behavior, as of 2026-10
Sources
- https://developers.notion.com/reference/request-limits
- https://developers.notion.com/reference/errors
- https://github.com/makenotion/notion-sdk-js/issues/172
Have your agent know this before it fails
claude mcp add --transport http footgun https://getfootgun.com/api/mcp