For Developers
Errors
Every status the Senso API returns, what causes it, and what to do about it.
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, no such endpoint, or it belongs to another organization | Confirm the id and the organization — and check whether the path itself exists, see below |
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:
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.
A 404 has two different causes, and they look different
404 answers two unrelated mistakes: the endpoint does not exist, or the endpoint exists and the resource does not. Which one you are looking at is visible in the shape of the response.
| What you sent | What comes back | What it means |
|---|---|---|
| A path with no route behind it | A plain-text 404, from the router, before any handler runs | The URL is wrong. Check the version prefix, the spelling, and whether the operation is in the OpenAPI spec at all |
| A real path with an id that resolves to nothing | A JSON error body | The URL is right. Check the id, and check the key belongs to the organization that owns it |
404.This is an observation about how the services behave, not a promise about their bodies. Do not branch on it in code — see the next section.
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
- API Keys — getting a key and proving it works
- API Reference — the responses each operation declares