Senso Documentation — The Trusted AI Answer

Senso signals failure with the HTTP status code, and explains it in a JSON body. Branch on the status first; the body tells you which case you hit.

The error body

Nearly every error comes back with the same two fields:

json

{ "status": 404, "message": "Node not found" }

status repeats the HTTP status. message is written for people: log it and show it, but do not match on its text.

A request whose body fails validation lists each problem instead:

json

{
  "status": 400,
  "errors": [
    { "field": "type", "message": "Must be one of: decision consideration awareness evaluation" }
  ]
}

A 402 carries a code you can branch on: insufficient_credits or spending_limit_reached.

Each operation's possible errors and their bodies are in the API Reference.

Every status

Status	Means	What to do
`400`	The request was malformed, or a field failed validation	Check the `message` or `errors`
`401`	The API key is missing or not valid	Send the key in the `X-API-Key` header. See below
`402`	Out of credits, or over the spending limit	Check `code`, and your balance with `GET /org/credits/balance`
`403`	The key is valid, but this request is not allowed	See below: it has a few different causes
`404`	No such endpoint, or no such resource that you can see	See below
`409`	Conflicts with something that already exists or is still running	For example, text identical to a document you already have, deleting a document that is still processing, or starting a website import while one is running. Read the `message` before retrying
`422`	The request is valid but cannot be carried out	For example, an upload in which no file could be accepted (the body still lists each file's result), turning on auto-publish with no destination set up, or a website import with no website on file
`429`	Too many requests	Back off and retry. See Limits
`500`	Something failed on Senso's side	Retry once. For a request that changes something, check whether it took effect before retrying
`502`	A service Senso depends on failed	Most often while publishing or unpublishing. Check the content's status before retrying
`503`	A service is temporarily unavailable	Retry with backoff

401: the key is missing or not valid

json

{ "status": 401, "message": "Organization API key or valid JWT token required" }

The same answer covers a missing key, a key that is wrong or expired, and a key sent in the wrong header. Send it as X-API-Key: <your key>, not as Authorization: Bearer. Keys from senso login expire after seven days. API Keys shows how to get one.

403: the key is valid, but this is not allowed

The message says which case it is:

`message`	Cause
`This action requires user authentication`	The operation needs a person signed in to the Senso app. Creating, changing or revoking API keys, and approving a device sign-in, cannot be done with an API key
`Your organization doesn't have access to this product`	Your organization does not have the Senso product this endpoint belongs to
`No KB scope configured. An admin must grant access to KB content before searching.`	The key is restricted to knowledge base folders, and has none
`You do not have permission to modify this resource`	You can see the file or folder, but your access to it does not include changing it
`Industry does not match the organization's industry`	You can import prompts only from your organization's own industry

A key restricted to some folders keeps working on every other endpoint, which is why a 403 or 404 from the knowledge base can be surprising. GET /org/api-keys shows whether each key is scoped, and GET /org/api-keys/{id}/kb-permissions lists its folders. Permissions explains roles and folder access.

404: no such endpoint, or nothing you can see

A 404 has two causes, and the body tells them apart:

What comes back	What it means
Plain text: `404 page not found`	The path does not exist. Check the spelling and the `/api/v1` prefix
JSON, such as `{"status": 404, "message": "Node not found"}`	The path exists, but the id does not match anything you can see

A file or folder you do not have at least view access to answers 404, not 403. To you, it does not exist. Check the id, and check that your key belongs to the organization that owns it and can see that folder.

A knowledge base document and generated content have separate endpoints. A knowledge base document's id sent to /org/content/{id} is a 400, and is read through /org/kb/nodes/{id} instead.

Next steps

Permissions — roles, folder access and API key scopes
API Keys — getting a key and checking it works
Limits — rate limits and paging
API Reference — every operation's errors and bodies