Errors

This reference documents all error responses returned by the Partners API, including HTTP status codes, response shapes, and the conditions that trigger each error.

Error response format

All errors follow a consistent JSON structure:

{
  "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)

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 (`PATCH`/`PUT`/`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

`500 Internal Server Error`

An unexpected error occurred on the server.

Error	Message	Cause
`Server Error`	`An unexpected error occurred`	An unhandled exception in the API layer
`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`