Error Responses

Kyberis errors are structured for agent branching.

Response Envelope

Field	Meaning
`error_code`	Stable machine-readable error code
`message`	Human-readable summary
`status_code`	HTTP status code
`request_id`	Request correlation ID
`run_id`	Agent run ID when context is available
`step_id`	Agent step ID when context is available
`required_scopes`	Scopes needed to call the endpoint
`missing_scopes`	Scopes absent from the current credential
`reason`	Additional machine-readable blocker
`retry_after_seconds`	Backoff hint for rate limits
`requested_credits` / `available_credits`	Credit exhaustion details

Common Statuses

Status	Typical Cause	Agent action
`400`	Missing or malformed `agent_context`, subject/query conflict, bad request shape	Fix the payload.
`401`	Missing, invalid, or expired credentials	Refresh credentials or ask for a valid key.
`403`	Missing scope	Ask for a key with `missing_scopes`; compare with `required_scopes` for the full endpoint requirement.
`422`	Schema validation failure	Correct fields, enums, limits, or types.
`429`	Rate limit or repeated auth failures	Back off and honor `retry_after_seconds`.
`5xx`	Transient service failure	Retry conservatively with backoff.

Do not Retry Blindly

Do not retry these without changing something:

insufficient_scope
credit_exhausted
batch_limit_exceeded
validation errors
malformed or expired connect tokens

Error Report Shape

When a Kyberis call fails, report:

Kyberis call failed: <endpoint>
status: <status_code>
error_code: <error_code>
request_id: <request_id>
run_id: <run_id>
step_id: <step_id>
required action: <credential, scope, payload, retry, or support action>

⌘I

Getting started

Install Kyberis

Platform integrations

Threat investigations

Sample investigations

Interpret responses

Response Envelope

Common Statuses

Do not Retry Blindly

Error Report Shape