TG Cerber API

Errors

Errors use HTTP status codes and one JSON shape: { "error": { "type", "code", "message", "param" } }.

type	Status	Meaning
`invalid_request_error`	400, 409	The request is malformed, a parameter is missing, unknown or invalid, or it conflicts with the current state.
`authentication_error`	401	No credential, or one that is invalid, expired or revoked.
`permission_error`	403	The credential lacks the scope, or its admin's role may not do this.
`not_found_error`	404	No such object in this organization, or one the admin may not see.
`rate_limit_error`	429	Too many requests.
`api_error`	5xx	A problem on our side; retry later and quote the Request-Id.

type is what your code branches on; code names the specific reason — the same code the console uses (examples: parameter_invalid, invalid_api_key, insufficient_scope, superadmin_required, resource_missing, rate_limited, archive_password_changed); message is a sentence for a person; param names the input at fault.

A missing scope is permission_error / insufficient_scope, with WWW-Authenticate: Bearer error="insufficient_scope", scope="…".

An object the admin may not see answers 404, exactly like one that does not exist, so the API never confirms that it exists.

archive_password_changed (403) means the organization's archive password changed: an admin must enter the new password for that connection in TG Cerber → Connect AI.

Every response carries a Request-Id header — quote it to support.

400 example

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must be at most 100.",
    "param": "limit"
  }
}

401 example

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "This API key is invalid or was revoked."
  }
}

403 example

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not have the org:read scope. Issue an API key with it, or reconnect and approve it."
  }
}

404 example

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such employee in this organization"
  }
}

429 example

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests: at most 120 a minute per credential. Retry after 12 s."
  }
}