Error Reference¶

Every Xybern API response includes an ok field. When ok is false, an error object is returned with a machine-readable code and a human-readable message.

{
  "ok": false,
  "error": {
    "code": "policy_not_found",
    "message": "No policy found with id: policy_abc123",
    "request_id": "req_7f3a9c"
  }
}

HTTP Status Codes¶

Status	Meaning
`200`	Request succeeded
`400`	Bad request, invalid or missing parameters
`401`	Unauthorised, missing or invalid API key
`403`	Forbidden, valid key but insufficient permissions
`404`	Resource not found
`409`	Conflict, resource already exists
`422`	Unprocessable, request is valid but semantically incorrect
`429`	Rate limited, slow down requests
`500`	Internal server error
`503`	Service temporarily unavailable

Error Codes¶

Authentication¶

Code	Status	Description
`missing_api_key`	401	No `X-API-Key` header was provided
`invalid_api_key`	401	The API key is malformed or does not exist
`expired_api_key`	401	The API key has been revoked or expired
`insufficient_permissions`	403	The API key does not have permission for this operation

Enforcement¶

Code	Status	Description
`agent_not_found`	404	No registered agent with the provided `agent_id`
`agent_suspended`	403	The agent has been suspended and cannot perform actions
`decision_not_found`	404	No decision found with the provided `decision_id`
`escalation_not_found`	404	No escalation found with the provided escalation ID
`escalation_already_resolved`	409	The escalation has already been approved or rejected
`invalid_action_type`	400	`action_type` is missing or contains invalid characters
`invalid_chain`	422	`chain_step` provided without a `chain_id`, or chain is malformed
`breakglass_cooldown`	429	Agent has exceeded the breakglass limit (3 per 30 minutes)
`temporal_window_expired`	403	The temporal permission window for this agent has expired
`temporal_window_scope_exceeded`	403	The requested action is outside the granted temporal window scopes

Policies¶

Code	Status	Description
`policy_not_found`	404	No policy found with the provided `policy_id`
`policy_name_conflict`	409	A policy with this name already exists
`policy_invalid_syntax`	400	The policy definition contains a syntax error
`policy_circular_dependency`	422	Policy references create a circular dependency
`policy_limit_reached`	429	Workspace policy limit reached, contact support to increase

Agents & Registry¶

Code	Status	Description
`agent_name_conflict`	409	An agent with this name is already registered
`agent_limit_reached`	429	Workspace agent limit reached
`credential_not_found`	404	No credential found for this agent
`credential_rotation_failed`	500	Credential rotation could not be completed, retry or contact support

LLM Gateway¶

Code	Status	Description
`provider_not_supported`	400	The specified LLM provider is not supported
`provider_connection_failed`	503	Could not reach the upstream LLM provider
`prompt_blocked`	403	The prompt was blocked by an active enforcement policy
`completion_blocked`	403	The completion was blocked before being returned to your application

General¶

Code	Status	Description
`invalid_request`	400	Request body is malformed or missing required fields
`resource_not_found`	404	The requested resource does not exist
`rate_limited`	429	Too many requests, implement exponential backoff
`internal_error`	500	Unexpected server error, retry with backoff, contact support if persistent
`service_unavailable`	503	Xybern is temporarily unavailable, check status.xybern.com

Handling Errors¶

import requests
import time

def enforce_with_retry(payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://www.xybern.com/api/v1/enforce/intercept",
            headers={"X-API-Key": api_key},
            json=payload
        ).json()

        if resp.get("ok"):
            return resp

        code = resp.get("error", {}).get("code", "")

        if code in ("rate_limited", "service_unavailable", "internal_error"):
            time.sleep(2 ** attempt)  # exponential backoff
            continue

        if code in ("invalid_api_key", "agent_suspended", "prompt_blocked"):
            raise PermissionError(f"Xybern blocked: {code}")

        raise RuntimeError(f"Xybern error: {code}")

    raise RuntimeError("Max retries exceeded")

Rate limits

On 429 rate_limited, always use exponential backoff. The default workspace limit is 1,000 requests per minute. Contact support to increase limits for production workloads.