Error codes

DeepIntShield SDK errors expose a stable machine-readable code and a trusted description. Branch on error.code or ErrorCode, not exception text or a gateway response message.

from deepintshield import DeepintShieldError, ErrorCode

try:
    result = shield.guard(stage="input", input="Transfer the funds")
except DeepintShieldError as error:
    if error.code == ErrorCode.RATE_LIMITED.value:
        schedule_retry(error)
    elif error.code == ErrorCode.GUARDRAIL_BLOCKED.value:
        return safe_refusal(error.description)
    else:
        log.error(
            "DeepIntShield operation failed",
            extra={
                "code": error.code,
                "status_code": error.status_code,
                "retryable": error.retryable,
            },
        )
        raise

Public error contract

The following names are importable from deepintshield:

from deepintshield import (
    ERROR_CATALOG,
    DeepintShieldBlockedError,
    DeepintShieldError,
    ErrorCategory,
    ErrorCode,
    ErrorDefinition,
    get_error_definition,
    get_exception_error_code,
    iter_error_definitions,
)

DeepintShieldError preserves the original constructor and adds keyword-only structured metadata:

DeepintShieldError(
    message,
    status_code=None,
    payload=None,
    *,
    code=None,
    details=None,
)

Field	Use
code	Stable lowercase identifier for program logic.
description	Catalog-controlled, display-safe summary.
retryable	Catalog hint; your application still decides whether and how to retry.
details	Structured caller/request context such as status_code, stage, or the bounded original response_code. Review it before displaying or logging it.
status_code	HTTP status when the failure came from a gateway response.
message	Raw diagnostic text. Treat it as untrusted and potentially sensitive.
payload	Raw gateway payload. Keep it out of user responses and unprotected logs.

error.to_dict() returns only code, description, status_code, retryable, and a copy of details. It intentionally omits raw message and payload, but details can still contain caller/request diagnostic data and is not universally sanitized. DeepintShieldBlockedError defaults to guardrail_blocked and also exposes its guardrail stage and decision metadata.

Native exception compatibility

Some SDK paths preserve the exception type callers already expect and annotate the instance with code, description, retryable, and details:

Boundary	Preserved type examples
Network/timeout	httpx.HTTPError, httpx.TimeoutException
Optional provider/framework dependency	ImportError
Invalid environment value	ValueError
Unsupported RAG wrapper target	TypeError
Unknown framework binder or operation	ValueError, AttributeError
Agentic application boundary	PermissionError, ConnectionError, RuntimeError

These are not subclasses of DeepintShieldError. Catch the narrow native type appropriate to the operation, then use get_exception_error_code(error) to read its SDK annotation. Do not catch every ImportError or ValueError in a large block and assume it came from DeepIntShield; an empty helper result means the exception has no recognized SDK contract.

Catalog lookup

from deepintshield import ErrorCategory, get_error_definition, iter_error_definitions

definition = get_error_definition("rate-limited")  # hyphens normalize to underscores
if definition:
    print(definition.description)
    print(definition.retryable)
    print(definition.action)
    print(definition.dashboard_path)

for definition in iter_error_definitions(ErrorCategory.MCP):
    print(definition.code, definition.description)

ERROR_CATALOG is an immutable mapping and each ErrorDefinition is frozen. Lookup is an in-memory O(1) mapping operation; iteration is deterministic. These catalog operations perform no network or filesystem I/O. That local property is not an end-to-end latency guarantee for the SDK operation that produced an error.

An unknown code returns None; an unknown category returns an empty tuple. Keep a generic fallback so applications remain compatible when a newer SDK adds a code.

Application-facing Agentic exceptions

Framework boundaries retain conventional Python exception types:

• PermissionError means the operation was denied.
• ConnectionError means the Agentic gateway or its response was unusable.
• RuntimeError covers approvals, configuration, dependencies, registration, and blueprint lifecycle stops.

Use get_exception_error_code() to read their safe marker. It also works with DeepintShieldError and does not expose the SDK’s private compatibility attribute:

from deepintshield import get_error_definition, get_exception_error_code

try:
    governed_tool()
except (PermissionError, ConnectionError, RuntimeError) as error:
    code = get_exception_error_code(error)
    definition = get_error_definition(code)
    if definition is None:
        raise
    log.warning(
        definition.description,
        extra={"code": code, "retryable": definition.retryable},
    )

Malformed values and ordinary exception prose produce an empty string. A bounded, future Agentic code may be returned before the local catalog recognizes it, so always handle definition is None.

Response-code normalization

For an HTTP failure, the SDK resolves the stable code in this order:

1. An explicit SDK code= override.
2. A recognized code in error.code, top-level code, error_code, or a code-shaped string in error.
3. A semantic status mapping: 401 → authentication_failed, 402 → feature_locked, 403 → permission_denied, 404 → resource_not_found, 408 → transport_timeout, 409 → conflict, and 429 → rate_limited.
4. The feature-specific fallback supplied by the SDK surface.
5. server_error for remaining 5xx responses, otherwise http_error.

Codes are lowercased and hyphens become underscores. Common gateway aliases normalize as follows:

Gateway alias	Stable SDK code
unauthenticated, authentication_error, unauthorized	authentication_failed
forbidden	permission_denied
not_found	resource_not_found
rate_limit_exceeded, too_many_requests	rate_limited

An unknown response code cannot replace the stable generic error.code. When it matches the bounded code grammar, it remains available as error.details["response_code"] for diagnosis.

Retry safely

retryable=True means the failure may be transient; it does not mean the SDK automatically retries or that replaying the operation is safe.

• Retry only idempotent operations, or use your own idempotency key.
• Apply capped exponential backoff with jitter and honor Retry-After when the gateway provides it.
• Bound attempts with a deadline and circuit breaker.
• Do not automatically retry denials, validation errors, approval-required outcomes, quota failures, or incomplete registration/blueprint states.
• Treat Agentic failures as fail-closed. Restore the indicated service or complete the dashboard workflow before retrying.
• Test timeout, rate-limit, partial-response, and concurrency behavior under the traffic and provider mix you operate.

Stability policy

Error-code string values and their meanings are compatibility contracts. Existing values are not repurposed; future releases may add values. Categories, descriptions, operator actions, and dashboard paths are catalog metadata and may be clarified without changing the code’s meaning. Persist the code for durable automation and observability, not the English description.

Version both sides

The gateway can evolve independently of the SDK. Keep the generic fallback, retain bounded unknown response codes only for protected diagnostics, and test your supported SDK/gateway combinations before rollout.

Complete catalog

The tables below list every code in the current SDK catalog. “Retryable” is the catalog hint described above, not permission to replay a non-idempotent action.

Client

Code	Description	Retryable
sdk_error	The DeepIntShield SDK operation failed.	No
client_closed	The DeepIntShield client has already been closed.	No

Configuration

Code	Description	Retryable
configuration_error	The SDK configuration is invalid or incomplete.	No
virtual_key_missing	An active workspace Virtual Key is required.	No
optional_dependency_missing	A required optional dependency is not installed.	No
feature_locked	This feature is not enabled for the workspace.	No

Transport

Code	Description	Retryable
transport_error	The gateway could not be reached.	Yes
transport_timeout	The gateway request timed out.	Yes
http_error	The gateway rejected the request.	No
invalid_response	The gateway returned an invalid response.	Yes
authentication_failed	Gateway authentication failed.	No
permission_denied	The requested gateway operation is not permitted.	No
resource_not_found	The requested gateway resource was not found.	No
conflict	The request conflicts with the current gateway state.	No
rate_limited	The gateway rate limit was exceeded.	Yes
quota_exceeded	The workspace quota was exceeded.	No
server_error	The gateway failed to process the request.	Yes
internal_error	The gateway encountered an internal error.	Yes

Chat

Code	Description	Retryable
chat_request_failed	The chat completion request failed.	No
chat_stream_invalid_event	The chat stream returned a malformed event.	No

Guardrail

Code	Description	Retryable
guardrail_evaluation_failed	The guardrail evaluation failed.	No
guardrail_blocked	A guardrail blocked the operation.	No

RAG

Code	Description	Retryable
rag_evaluation_failed	The RAG security evaluation failed.	No
rag_retriever_unsupported	The retriever exposes no supported retrieval method.	No
rag_embedder_unsupported	The embedder exposes no supported embedding method.	No

Agent

Code	Description	Retryable
agent_invocation_invalid	The tool invocation is incomplete or invalid.	No

MCP

Code	Description	Retryable
mcp_dependency_missing	A supported official MCP Python SDK is not available.	No
mcp_connection_failed	The MCP server connection failed.	No
mcp_protocol_error	The MCP server returned an invalid protocol response.	No
mcp_execution_failed	The MCP tool execution failed.	No
mcp_discovery_failed	MCP tool discovery failed.	No
mcp_tool_name_invalid	The MCP tool name is not qualified with a server prefix.	No
mcp_arguments_invalid	The MCP tool arguments are not valid JSON.	No
mcp_tool_authorization_denied	Canonical Agentic authorization denied the MCP tool execution.	No
mcp_tool_authorization_unavailable	Canonical Agentic authorization for the MCP tool is unavailable.	Yes
mcp_tool_approval_required	The MCP tool execution is waiting for approval.	No

Provider

Code	Description	Retryable
provider_dependency_missing	The selected provider dependency is not installed.	No
provider_initialization_failed	The selected provider could not be initialized.	No

Framework

Code	Description	Retryable
framework_binder_not_found	The requested framework binder is not supported.	No
framework_binder_attribute_missing	The framework does not provide the requested binder operation.	No
framework_dependency_missing	The selected agent framework dependency is missing.	No
framework_integration_unsupported	The installed agent framework version is not supported.	No

Validation

Code	Description	Retryable
invalid_argument	A request argument is invalid.	No
validation_error	SDK input validation failed.	No

Agentic governance and PDP

Code	Description	Retryable
agentic_error	The governed operation stopped safely.	No
governance_configuration_error	Agent governance is not fully configured.	No
guardrail_denied	Agentic authorization denied this operation.	No
require_approval	This operation is waiting for approval.	No
mask_obligation_unsupported	A required data-protection obligation could not be applied safely.	No
gateway_unavailable	The Agentic gateway is unavailable.	Yes
invalid_gateway_response	The Agentic gateway returned an invalid response.	Yes
agent_registration_pending	This agent is waiting for registration approval.	No
agent_not_registered	This agent is not registered.	No
agent_registration_denied	This agent’s registration was denied.	No
agent_registration_not_ready	This agent’s registration review is incomplete.	No
agent_registration_approval_required	This agent requires registration approval.	No
agent_registration_quota_exceeded	This reporting key has reached its pending-registration limit.	No
agent_registration_review_stale	The agent registration changed during review.	No
agent_registration_review_conflict	The agent registration changed during review.	No
agent_approval_pending	This operation is waiting for approval.	No
guardrail_approval_pending	This operation is waiting for approval.	No
approval_required	This operation is waiting for approval.	No
approval_access_denied	You are not allowed to review this approval.	No
approval_store_unavailable	The durable approval service is unavailable.	Yes
authz_store_unavailable	The authorization service is unavailable.	Yes
legacy_pdp_unavailable	The configured policy decision service is unavailable.	Yes
agent_blueprint_review_pending	This code blueprint is waiting for security review.	No
agent_blueprint_review_denied	This code blueprint was denied.	No
blueprint_scan_unavailable	The code blueprint could not be scanned safely.	Yes
blueprint_scan_required	An approved code blueprint is required.	No
blueprint_scanning_required	Static code-blueprint scanning must remain enabled.	No
blueprint_registration_failed	The code blueprint could not be registered safely.	Yes
blueprint_coverage_incomplete	The executable code evidence is incomplete.	No
blueprint_manifest_too_large	The executable code blueprint exceeds the safe size limit.	No
blueprint_remote_tool_unverified	A remote tool could not be verified against an MCP connection.	No
blueprint_mcp_inventory_unavailable	The MCP tool inventory is unavailable.	Yes
blueprint_model_scan_pending	Code model analysis is still running.	Yes
blueprint_model_scan_failed	Code model analysis failed safely.	Yes
blueprint_model_unavailable	The configured code-analysis model is unavailable.	Yes
invalid_blueprint_manifest	The code blueprint evidence is invalid.	No
credential_configuration_error	The workload identity is not fully configured.	No
credential_provider_unsupported	The workload identity provider is unsupported.	No
credential_dependency_missing	A workload identity dependency is missing.	No
credential_exchange_failed	The workload identity exchange failed.	Yes
agent_decision_context_missing	The Agentic decision context is incomplete.	No
principal_identifier_missing	A stable principal identity is required.	No
registry_discovery_empty	No discoverable agent topology was provided.	No
registry_discovery_invalid	The agent discovery payload is invalid.	No
registry_discovery_pending	Agent discovery is already in progress.	Yes
registry_discovery_rejected	The agent registry rejected the discovery report.	No
registry_discovery_unavailable	The agent discovery service is unavailable.	Yes
registry_unavailable	The agent registry is unavailable.	Yes
workload_proof_required	Verified workload identity proof is required.	No
agent_access_denied	Agentic authorization denied this operation.	No
authorization_denied	Agentic authorization denied this operation.	No
authz_engine_error	Agentic authorization denied this operation.	No
context_deny	Agentic authorization denied this operation.	No
no_store	Agentic authorization denied this operation.	No
obo_action_not_allowed	Agentic authorization denied this operation.	No
obo_delegation_required	Agentic authorization denied this operation.	No
obo_no_acts_for	Agentic authorization denied this operation.	No
obo_scope_mismatch	Agentic authorization denied this operation.	No
obo_tool_not_allowed	Agentic authorization denied this operation.	No
obo_user_lacks_perm	Agentic authorization denied this operation.	No
obo_user_mismatch	Agentic authorization denied this operation.	No

The action and dashboard_path fields in each live ErrorDefinition provide the exact operator guidance and console destination for errors that require a workflow. Prefer those fields over maintaining a second action map in your application.