Errors

The Holos API returns standard HTTP status codes and a consistent JSON error body.

Error format

{
  "error": "Not found",
  "message": "Skill not found",
  "statusCode": 404
}

Field	Description
`error`	Short error label
`message`	Human-readable description
`statusCode`	HTTP status code (mirrors the response status)

Status codes

Code	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request: invalid or missing parameters
`401`	Unauthorized: missing or invalid session token
`403`	Forbidden: authenticated but insufficient role
`404`	Not found: resource doesn’t exist or is outside your org
`409`	Conflict: duplicate resource (e.g. duplicate `skillId` within an org)
`422`	Unprocessable: validation failed (Joi schema rejection)
`500`	Internal server error

Authorization errors

401 and 403 are distinct:

401 means no valid session token was provided
403 means the token is valid but the user’s role doesn’t permit the action

Both indicate an auth failure but require different handling: 401 should trigger a re-auth flow, while 403 is a permission issue that re-auth won’t fix.

Overview

Concepts

Resources

Error format

Status codes

Authorization errors

​Error format

​Status codes

​Authorization errors

Error format

Status codes

Authorization errors