| 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" | The token lacks permission, or the request exceeds a workspace block limit. The message explains the cause. | "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 later." |
| 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, or it could not build the response in time. This can occur when a request takes longer than 60 seconds, the maximum request timeout. A write can save its change and still return this code, so check additional_data.retry_guidance before you retry it. More details on retrying a write that returns 503. | "Notion is unavailable, please try again later." or "The change was saved, but the response could not be built in time." |
| 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" or "The request timed out. Please try again later." |
| 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." |
