Errors

Partners API errors contain an error category and a human-readable message. Validation and concurrency failures add fields relevant to the failed operation.

Error response format

A typical route-level error looks like:

{
  "error": "Unauthorized",
  "message": "Valid API key required",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Always present	Description
`error`	string	Yes	Short error category
`message`	string	Yes	Human-readable explanation
`requestId`	string	Most responses	Unique request identifier (useful for support)
`errors`	array	Validation responses	Field or operation issues, often with a `path` and `message`

HTTP status codes

`200 OK`

Successful read (GET), update (PATCH, PUT), or delete (DELETE) operation.

`201 Created`

Successful document creation (POST).

`400 Bad Request`

The request is malformed or missing required information.

Error	Message	Cause
`Missing tenant`	`Tenant slug or identifier must be provided`	No tenant header (`x-basker-tenant-id` or `x-basker-tenant-slug`) and no tenant path segment
`Unsupported API version`	`Version {version} is not supported. Supported versions: 2025-07, 2026-02`	The version segment in the URL is not a supported version
`Missing resource`	`Provide a collection path after the tenant segment`	The URL path after the tenant segment is empty
`Missing identifier`	`Provide a document id after the collection`	A `PATCH`, `PUT`, or `DELETE` request was made without an ID in the path
`Invalid JSON body`	`Request body must be valid JSON`	The request body for a `POST`, `PUT`, or `PATCH` request is not valid JSON

`401 Unauthorized`

Authentication failed.

Error	Message	Cause
`Unauthorized`	`Valid API key required`	The `Authorization` header is missing, does not follow the `users API-Key` format, or the key does not match any user

`403 Forbidden`

The request is authenticated but not permitted on this endpoint.

Error	Message	Cause
`Forbidden`	`API keys must use the Partners API at /partners/:version/:tenant/*`	An API key was sent to the native Basker CMS API (`/api/`) instead of the Partners API (`/partners/`)

`404 Not Found`

The requested resource does not exist.

Error	Message	Cause
`Tenant not found`	`Unable to resolve tenant from provided headers or path`	The tenant ID or slug does not match any tenant in the system
`Not Found`	`Document not found for tenant`	The document ID does not exist, does not belong to the resolved tenant, or (on a write using `PATCH`, `PUT`, or `DELETE`) is owned by another member of your tenant group. Shared records are readable across the group but writable only by their owning tenant.
`Not Found`	`Route not found`	The URL path does not match any registered route

`409 Conflict`

Block and theme-setting mutations return 409 when the record changed after the ifUpdatedAt value supplied by the client. Refetch the draft and reconcile it before retrying.

`422 Unprocessable Entity`

Dedicated mutation routes return 422 for unknown block types, fields, settings, guarded fields, or invalid configured values. Use the matching …/schema endpoint to rebuild the request.

`429 Too Many Requests`

The API key exceeded its current read or write limit. Wait for the number of seconds in Retry-After; see Rate limits.

`500 Internal Server Error`

An unexpected error occurred on the server.

Error	Message	Cause
`Server Error`	`Unexpected error while processing the request`	An error during query execution or document processing
`Tenant context missing`	`Unable to resolve tenant for this request`	Internal error -- tenant context was expected but not available

Errors by scenario

Scenario	Status	Error	Message
No `Authorization` header	`401`	`Unauthorized`	`Valid API key required`
Invalid API key	`401`	`Unauthorized`	`Valid API key required`
API key sent to `/api/` instead of `/partners/`	`403`	`Forbidden`	`API keys must use the Partners API at /partners/:version/:tenant/*`
No tenant header or path segment	`400`	`Missing tenant`	`Tenant slug or identifier must be provided`
Tenant slug does not exist	`404`	`Tenant not found`	`Unable to resolve tenant from provided headers or path`
Unsupported API version in URL	`400`	`Unsupported API version`	`Version {version} is not supported...`
Document ID not found in tenant	`404`	`Not Found`	`Document not found for tenant`
Write against another tenant-group member's record	`404`	`Not Found`	`Document not found for tenant`
Invalid URL path	`404`	`Not Found`	`Route not found`
Malformed JSON request body	`400`	`Invalid JSON body`	`Request body must be valid JSON`
Server-side exception	`500`	`Server Error`	`An unexpected error occurred`