[metadata]
apple-mobile-web-app-title: Notion Docs
application-name: Notion Docs
description: Responses from the API use HTTP response codes to indicate general classes of success and error.
generator: Mintlify
msapplication-TileColor: #000
msapplication-config: /mintlify-assets/_mintlify/favicons/notion-demo/1PaJq9z3waub4TpE/_generated/favicon/browserconfig.xml
og:description: Responses from the API use HTTP response codes to indicate general classes of success and error.
og:image: https://notion-demo.mintlify.app/images/og-image.png
og:image:height: 630
og:image:width: 1200
og:site_name: Notion Docs
og:title: Status codes - Notion Docs
og:type: website
og:url: https://developers.notion.com/reference/status-codes
twitter:card: summary_large_image
twitter:description: Responses from the API use HTTP response codes to indicate general classes of success and error.
twitter:image: https://notion-demo.mintlify.app/images/og-image.png
twitter:image:height: 630
twitter:image:width: 1200
twitter:title: Status codes - Notion Docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://developers.notion.com/reference/status-codes

[document-links]
/llms.txt: /llms.txt
API Reference: /reference/intro
Admin API: /reference/admin/intro
CLI Reference: /cli/get-started/overview
Changelog: /page/changelog
Connection capabilities: /reference/capabilities
Database: /reference/database
Developer portal: https://www.notion.so/developers
Emoji and icon: /reference/emoji-and-icon
Examples: /page/examples
File Upload: /reference/file-upload
Guides: /guides/get-started/overview
Introduction: /reference/intro
Log in: https://www.notion.com/login
More details on rate limits: /reference/request-limits
Notion Docs home page: /
Notion support: https://www.notion.com/help
OAuth 2.0 documentation: https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
Parent: /reference/parent-object
Request limits Previous: /reference/request-limits
Request limits: /reference/request-limits
Retrieve an async task Next: /reference/retrieve-async-task
Status codes: /reference/status-codes
Unfurl attribute (Link Previews): /reference/unfurl-attribute-object
User: /reference/user
Versioning: /reference/versioning
Versioning: /reference/versioning#beta-versions
View: /reference/view
Workers: /workers/get-started/overview
slack: https://join.slack.com/t/notiondevs/shared_invite/zt-3u9oid9q8-HLUBmMVWYK~g9HFo4U4raA
x: https://x.com/NotionDevs

[structured-data]
{"@context":"https://schema.org","@graph":[{"@id":"https://developers.notion.com/#organization","@type":"Organization","logo":{"@type":"ImageObject","url":"https://mintcdn.com/notion-demo/5YdhSbldE14t5Rna/logo/light.svg?fit=max&auto=format&n=5YdhSbldE14t5Rna&q=85&s=249f5693ad929397409bf9b51d6d539d"},"name":"Notion Docs","url":"https://developers.notion.com"},{"@id":"https://developers.notion.com#website","@type":"WebSite","name":"Notion Docs","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com"},{"@id":"https://developers.notion.com/reference/status-codes#webpage","@type":"WebPage","breadcrumb":{"@id":"https://developers.notion.com/reference/status-codes#breadcrumb"},"dateModified":"2026-07-29T16:39:25.727Z","description":"Responses from the API use HTTP response codes to indicate general classes of success and error.","isPartOf":{"@id":"https://developers.notion.com#website"},"name":"Status codes","url":"https://developers.notion.com/reference/status-codes"},{"@id":"https://developers.notion.com/reference/status-codes#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://developers.notion.com/reference/intro","name":"Notion API","position":1},{"@type":"ListItem","item":"https://developers.notion.com/reference/status-codes","name":"Status codes","position":2}]},{"@id":"https://developers.notion.com/reference/status-codes#article","@type":["Article","TechArticle"],"dateModified":"2026-07-29T16:39:25.727Z","description":"Responses from the API use HTTP response codes to indicate general classes of success and error.","headline":"Status codes","image":"https://developers.notion.com/images/og-image.png","isPartOf":{"@id":"https://developers.notion.com#website"},"mainEntityOfPage":{"@id":"https://developers.notion.com/reference/status-codes#webpage"},"name":"Status codes","publisher":{"@id":"https://developers.notion.com/#organization"},"url":"https://developers.notion.com/reference/status-codes"}]}

[content]
Status codes - Notion Docs
Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Notion Docs
home page
Search...
⌘
K
Ask Assistant
Log in
Developer portal
Developer portal
Search...
Navigation
Notion API
Status codes
Guides
API Reference
CLI Reference
Workers
Admin API
Changelog
Examples
Notion API
Introduction
Connection capabilities
Webhooks
Request limits
Status codes
Async tasks
Versioning
Objects
Block
Page
Database
Data source
View
Comment
File
User
Parent
Emoji and icon
Unfurl attribute (Link Previews)
Endpoints
Authentication
Blocks
Pages
Databases
Data sources
Databases (deprecated)
Comments
Views
File Uploads
Search
Users
Custom emojis
Webhook events
Pages
Databases
Data sources
Comments
File uploads
Views
On this page
Success codes
Error codes
Notion API
Status codes
Copy page
Copy page
Responses from the API use HTTP response codes to indicate general classes of success and error.
Copy page
Copy page
​
Success codes
HTTP status code
Description
200
Notion successfully processed the request.
​
Error codes
Error responses contain more detail about the error in the response body, in the
"code"
and
"message"
properties. Some error responses may also include an
"additional_data"
object with extra context, such as retry guidance or endpoint-specific details.
HTTP status code
"code"
Description
"message"
example
400
"invalid_json"
The request body could not be decoded as JSON.
"Error parsing JSON body."
400
"invalid_request_url"
The request URL is not valid.
"Invalid request URL"
400
"invalid_request"
This request is not supported.
"Unsupported request: <request name>."
400
"invalid_grant"
The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. See
OAuth 2.0 documentation
for more information.
"Invalid code: this code has been revoked."
400
"validation_error"
The request body does not match the schema for the expected parameters. Check the
"message"
property for more details.
"body failed validation: body.properties should be defined, instead was undefined."
400
"missing_version"
The request is missing the required
Notion-Version
header. See
Versioning
.
"Notion-Version header failed validation: Notion-Version header should be defined, instead was undefined."
400
"invalid_beta"
The
Notion-Beta
header is malformed, names an unknown beta, uses an unsupported revision, or is missing from an endpoint that requires it. See
Versioning
.
"Beta \"notion-as-code\" revision 2026-07-01 is no longer supported. Send Notion-Beta: notion-as-code-2026-07-31."
401
"unauthorized"
The bearer token is not valid.
"API token is invalid."
403
"restricted_resource"
Given the bearer token used, the client doesn’t have permission to perform this operation.
"API token does not have access to this resource."
404
"object_not_found"
Given the bearer token used, the resource does not exist. This error can also indicate that the resource has not been shared with owner of the bearer token. If the connection name is available, it will be included in the error message.
"Could not find database with ID: be907abe-510e-4116-a3d1-7ea71018c06f. Make sure the relevant pages and databases are shared with your connection \"My Connection\"."
409
"conflict_error"
The transaction could not be completed, potentially due to a data collision. Make sure the parameters are up to date and try again. We also use this HTTP status code in rare cases when our
File Upload
third-party data storage provider has downtime and sending file contents failed. In this case, please retry the request later.
"Conflict occurred while saving. Please try again."
429
"rate_limited"
This request exceeds the number of requests allowed. Slow down and try again.
More details on rate limits
.
"You have been rate limited. Please try again in a few minutes."
500
"internal_server_error"
An unexpected error occurred. Reach out to
Notion support
.
"Unexpected error occurred."
502
"bad_gateway"
Notion encountered an issue while attempting to complete this request (e.g., failed to establish a connection with an upstream server). Please try again.
"Bad Gateway"
503
"service_unavailable"
Notion is unavailable. This can occur when the time to respond to a request takes longer than 60 seconds, the maximum request timeout. Please try again later.
"Notion is unavailable, please try again later."
503
"database_connection_unavailable"
Notion’s database is unavailable or is not in a state that can be queried. Please try again later.
"Notion is unavailable, please try again later."
504
"gateway_timeout"
Notion timed out while attempting to complete this request. Please try again later.
"Gateway Timeout"
529
"service_overload"
Notion is temporarily overloaded. Respect the
Retry-After
response header and try again later.
"Notion is temporarily overloaded. Please try again later."
Request limits
Previous
Retrieve an async task
Next
⌘
I
x
slack
Assistant
Responses are generated using AI and may contain mistakes.
