For Developers

Errors

Every status the Senso API returns, what causes it, and what to do about it.

Senso signals failure with the HTTP status code. Branch on the status, not on the response body — bodies are not part of the published contract yet, and they differ between services.

Two statuses account for most surprises: 403 on a key that works everywhere else, and 401 on an endpoint that does not accept API keys at all. Both are explained below.

Every status

Status	Means	What to do
`400`	The request was malformed, or a field failed validation	Check required fields. Several objects accept a fixed set of keys and reject anything else — `brand_kit.guidelines` and `content_type.config` both return `400` on an unknown key
`401`	The credential is missing, malformed, or the wrong kind	Check the header name. If the key is good elsewhere, see below
`402`	Out of credits, or the spend limit is reached	Check `GET /org/credits/balance`
`403`	Authenticated, but not allowed to touch this	Almost always knowledge base scope. See below
`404`	No such resource, or it belongs to another organization	Confirm the id, and confirm the key is for the right organization
`409`	Conflict with something that already exists or is running	A duplicate name, or a source that is published and read-only. Read before retrying
`422`	Valid request, cannot be fulfilled	Every file was skipped as a duplicate, or auto-publish is on with no publisher configured
`429`	Too many requests	Back off. Only the suggestion endpoint and the MCP server enforce a limit today — see Limits
`500`	Something failed on our side	Safe to retry once. If it repeats, it is not you
`502`	A downstream service failed	Publishing to a destination, or the generation runner. The call failed; the destination may still be mid-change
`503`	A service is temporarily unavailable	Retry with backoff

403 is usually knowledge base scope

An API key can be restricted to specific folders. A scoped key gets 403 on anything outside its folders, and on the whole knowledge base if the scope is empty — while continuing to work on every other endpoint, which is what makes it confusing.

Check the key's scope before assuming the resource is missing:

bash

curl "https://apiv2.senso.ai/api/v1/org/api-keys" \
  -H "X-API-Key: $SENSO_API_KEY"

Full detail in Permissions.

401 can mean "not with a key"

A few endpoints require a signed-in user rather than an API key, and answer an otherwise valid key with 401. Organization and user management are the common cases. The API reference marks which authentication each operation takes.

Response bodies are not a contract yet

The status code is stable. The JSON alongside it is not published in the OpenAPI spec, so do not parse it or match on its strings — a message that reads like an identifier today may not be one next week.

Write handlers against the status, and log the body for humans.

Next steps

Limits — rate limits, pagination, and what can change
Permissions — user roles and API key scopes
Authentication — getting a key and proving it works
API Reference — the responses each operation declares