V2
Error Codes
Review the unified error response shape and every V2 API error code.
Error Codes
V2 endpoints use a shared JSON error shape.
{
"object": "error",
"status": 400,
"code": "validation_error",
"message": "parent.page_id is required",
"request_id": "req_xxx",
"details": [
{
"path": "parent.page_id",
"reason": "required"
}
]
}
Fields
| Field | Type | Description |
|---|---|---|
object |
string | Always error. |
status |
number | HTTP status code. |
code |
string | Stable application error code. |
message |
string | Human-readable message for debugging. |
request_id |
string | Identifier for support and tracing. |
details |
array | Optional structured validation or limit details. |
Codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | validation_error |
Request shape, field type, or required field is invalid. |
| 400 | unsupported_filter |
Filter syntax or property type is not supported. |
| 400 | unsupported_sort |
Sort syntax or property type is not supported. |
| 400 | unsupported_block_type |
Block type cannot be created or updated by the requested endpoint. |
| 401 | unauthorized |
Token is missing, invalid, or expired. |
| 403 | forbidden |
Token is valid but lacks scope, resource access, or workspace capability. |
| 404 | not_found |
Target resource does not exist or is not visible to the token. |
| 409 | conflict |
Write conflict, commonly from optimistic concurrency. |
| 409 | idempotency_conflict |
The idempotency key was reused with a different request body. |
| 429 | rate_limited |
Request rate is too high. |
| 500 | internal_error |
Unexpected server error. |
Notes
- Use
request_idwhen reporting failures. - Do not branch on
message; branch oncodeand HTTP status. 403 forbiddenmeans authentication succeeded but authorization or plan checks failed.404 not_foundcan be returned when a resource exists but the token cannot see it.