Errors | DJC AI API

Error shape

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "success": false,
  "error": "This token has knowledge:read — POST /api/ai/knowledge/bases/…/entries needs knowledge:write",
  "code": "INSUFFICIENT_SCOPE",
  "details": { "required": "knowledge:write", "scopes": ["knowledge:read"] }
}

error is for humans and may change wording; branch on code and the HTTP status. 401 responses carry success and error only.

Status codes

Status	Meaning	Retry?
`400`	Invalid body or a rule violation (unknown node type, duplicate question, limit exceeded). `details` carries field errors when there are any.	No — fix the request.
`401`	Missing, unrecognised, revoked or expired token.	No — check the token on the API page.
`402`	Your credit balance in this workspace is empty (`INSUFFICIENT_CREDITS`; balance in `details.balance`).	After topping up.
`403`	The token's scope does not cover this call (`INSUFFICIENT_SCOPE`), the resource is not enabled for the workspace, or the action is app-only (deleting a base).	No — adjust the token or do it in the app.
`404`	Base, entry, source, flow, node, edge or execution not found in your workspace — or the id is not a UUID.	No — check the id.
`500`	Something failed on our side.	Once, then contact support with the request.

Error codes

Code	What to do
`BAD_REQUEST`	Validation failed. Look at `details.fieldErrors`.
`INSUFFICIENT_SCOPE`	The token lacks the scope in `details.required`. Create a token with that access, or tick the resource.
`INSUFFICIENT_CREDITS`	Balance is 0 in this workspace. `details.balance` is the current value.
`FORBIDDEN`	Allowed for a session but not for this token — for example a legacy key on another base, or deleting a base.
`NOT_FOUND`	The id does not exist in your workspace.

Submissions are the one exception to "errors are HTTP errors": a failed extraction returns 200 with { "status": "error", "error": "…" } so that partial progress (entries already indexed) is not lost. The same applies to a node test that fails.