Common issues

Diagnose and fix the most frequent problems encountered when using the Partners API.

Prerequisites:

A Basker CMS account with API key
A working curl installation

Issues

1. Wrong authentication header format

Symptom: 401 Unauthorized with message Valid API key required, even though your key is correct.

Cause: The Authorization header does not use the required users API-Key prefix.

Fix: The header must be exactly:

Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890

Common mistakes:

Incorrect	Why it fails
`Authorization: Bearer a1b2c3d4-...`	Wrong prefix; `Bearer` is not accepted
`Authorization: API-Key a1b2c3d4-...`	Missing `users` before `API-Key`
`Authorization: users api-key a1b2c3d4-...`	Case-sensitive; `API-Key` must be capitalised
No `Authorization` header at all	Key is required on all non-public routes

Verify with:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/pages"

Result: 200 if the key and tenant are correct.

2. Missing tenant headers

Symptom: 400 Bad Request with message Tenant slug or identifier must be provided.

Cause: The request does not include any tenant identification.

Fix: Add one of these to your request:

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/pages"

Alternatively, use the x-basker-tenant-id header with the tenant's internal ID:

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-id: 6639a1c2f3b4a5d6e7f80099" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/pages"

See Understanding multi-tenancy for all resolution methods.

3. Invalid `where` clause JSON

Symptom: Empty results, unexpected results, or 500 Server Error.

Cause: The where parameter is not properly URL-encoded, or the JSON structure is malformed.

Fix: Always use --data-urlencode with curl -G to ensure proper encoding:

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[title][contains]=Traviata' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

If constructing URLs in application code, ensure brackets and special characters are percent-encoded. Common pitfalls:

Problem	Example	Fix
Unencoded brackets	`?where[title][equals]=test` in a URL string	Encode as `%5B` and `%5D`, or use your HTTP library's parameter encoding
Spaces in values	`?where[title][equals]=Swan Lake`	Encode spaces as `%20` or `+`
Missing operator	`?where[title]=test`	Add the operator: `?where[title][equals]=test`

4. Empty results when documents exist

Symptom: 200 response with "docs": [] and "totalDocs": 0, but you know documents exist.

Cause: One of several possibilities:

Tenant mismatch. You are querying a different tenant than the one containing your documents. Verify the tenant slug matches the one visible in your CMS admin panel. For collections shared in a tenant group, a read may legitimately span the group — see Tenant groups & shared data.
Wrong collection name. The collection slug must match exactly. Common mistakes:

Incorrect Correct
event events
page pages
eventInstances event-instances
customAttributes custom-attributes
organisation organizations (American spelling)
Overly restrictive filter. A where clause that matches no documents returns an empty array. Remove filters one at a time to isolate the issue.
Draft-only content. Documents that are not yet published are excluded by default. Add ?draft=true to include them.
Expected a shared record. A record owned by another member of your tenant group only appears when that collection is shared in your group (and, for a shareable collection, when the record has been shared with you). If the collection isn't shared — or your tenant has no group — the read returns only your own records. This is expected. See Tenant groups & shared data.

Incorrect	Correct
`event`	`events`
`page`	`pages`
`eventInstances`	`event-instances`
`customAttributes`	`custom-attributes`
`organisation`	`organizations` (American spelling)

Fix: Start with a minimal request (no filters) and confirm data exists:

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?limit=1"

Then add filters back incrementally.

5. Relationship fields return IDs instead of objects

Symptom: Fields like venue or season contain a plain string (the document ID) instead of a populated object.

Cause: The depth parameter is set to 0, or the relationship is beyond the population depth.

Fix: Increase the depth parameter or use populate to control expansion:

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?depth=1&limit=1"

Or use populate for fine-grained control:

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'populate[venues][title]=true' \
  --data-urlencode 'populate[venues][city]=true' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?limit=1"

6. API key rejected at `/api/` endpoint

Symptom: 403 Forbidden with message API keys must use the Partners API at /partners/:version/:tenant/*.

Cause: You sent an API key to the native Basker CMS REST API at /api/ instead of the Partners API at /partners/.

Fix: Change the URL from /api/ to /partners/{version}/{tenant}/:

https://api.basker.app/api/pages           (incorrect)
https://api.basker.app/partners/2026-02/royal-opera-house/pages  (correct)

7. Unsupported API version

Symptom: 400 Bad Request with message Version {version} is not supported.

Cause: The version segment in the URL does not match a supported version.

Fix: Use 2026-02 as the version:

https://api.basker.app/partners/2026-02/royal-opera-house/pages

Check supported versions at GET /partners/openapi.

8. Document not found but the ID looks correct

Symptom: 404 Not Found with message Document not found for tenant.

Cause: The document ID exists in a different tenant, or in a different collection within the same tenant — or you are writing to a record owned by another member of your tenant group. Shared records are readable across the group but writable only by their owning tenant.

Fix:

Confirm the ID belongs to the collection you are querying. An event ID will not be found in the pages collection.
Confirm the tenant slug is correct.
Verify the document exists by listing the collection first.
If a GET on the ID succeeds but a PATCH, PUT, or DELETE returns this 404, the record belongs to another member of your tenant group — those records are read-only through the API for non-owning tenants. See Tenant groups & shared data.

Result

When complete, you will have:

Identified the root cause of your API error
Applied the appropriate fix
Received a successful response

Error reference -- all error codes and status codes
How to authenticate -- correct authentication setup
Understanding multi-tenancy -- tenant resolution and tenant-group sharing
Collections overview -- correct collection slugs

On this page