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.
Registration, approval, access, and other administrator-resolved errors use a brief status followed by “Please contact your administrator.” Registration lifecycle codes use “Contact your administrator.” and, when the gateway supplied them, the registration reference and runtime-key thumbprint. Client messages do not include administration UI instructions or review links. Developer-side validation and dependency errors retain their actionable guidance. Stable codes, exception types, and retryability remain available for application handling.
Rendering administrator-resolved DeepintShieldError instances uses the
catalog summary. Their original message and payload remain diagnostic
fields; do not display them to application users or write them to unprotected
logs.
from deepintshield import DeepintShieldError, ErrorCode
def guarded_input(shield, schedule_retry, safe_refusal, log): 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, }, ) raisePublic error contract
Section titled “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
Section titled “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.
Inference through shield.openai() or shield.async_openai() retains the
native OpenAI exception contract, including APIStatusError and transport
exceptions. Other provider clients similarly retain their native types. A
transparent gateway policy rejection therefore does not automatically become
DeepintShieldBlockedError or carry an SDK annotation. Inspect the native
exception’s structured response body and status; use the catalog only for a
recognized gateway code. A provider access denial or quota failure is not proof
of a guardrail_blocked outcome.
Catalog lookup
Section titled “Catalog lookup”from deepintshield import ErrorCategory, get_error_definition, iter_error_definitions
definition = get_error_definition("rate-limited") # hyphens normalize to underscoresif definition: print(definition.description) print(definition.retryable)
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
Section titled “Application-facing Agentic exceptions”Framework boundaries retain conventional Python exception types:
PermissionErrormeans the operation was denied.ConnectionErrormeans the Agentic gateway or its response was unusable.RuntimeErrorcovers 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
Section titled “Response-code normalization”For an HTTP failure, the SDK resolves the stable code in this order:
- An explicit SDK
code=override. - A recognized code in
error.code, top-levelcode,error_code, or a code-shaped string inerror. - A semantic status mapping:
401→authentication_failed,402→feature_locked,403→permission_denied,404→resource_not_found,408→transport_timeout,409→conflict, and429→rate_limited. - The feature-specific fallback supplied by the SDK surface.
server_errorfor remaining 5xx responses, otherwisehttp_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
Section titled “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.
Native OpenAI clients retain their own retry policy. Configure max_retries
through shield.openai(...), shield.async_openai(...), or
shield.openai_config(...); account for those attempts before adding an
application retry loop. Direct shield.request(), RAG, and MCP helpers do not
add a general automatic retry policy.
- Retry only idempotent operations, or use your own idempotency key.
- Apply capped exponential backoff with jitter and honor
Retry-Afterwhen 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
Section titled “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.
Complete catalog
Section titled “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
Section titled “Client”| Code | Description | Retryable |
|---|---|---|
sdk_error | The DeepIntShield SDK operation failed. | No |
client_closed | The DeepIntShield client has already been closed. | No |
Configuration
Section titled “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. Please contact your administrator. | No |
Transport
Section titled “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. Please contact your administrator. | No |
permission_denied | The requested gateway operation is not permitted. Please contact your administrator. | 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. Please contact your administrator. | No |
server_error | The gateway failed to process the request. | Yes |
internal_error | The gateway encountered an internal error. | Yes |
| 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
Section titled “Guardrail”| Code | Description | Retryable |
|---|---|---|
guardrail_evaluation_failed | The guardrail evaluation failed. | No |
guardrail_blocked | A guardrail blocked the operation. Please contact your administrator. | No |
| 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 |
RAG source lookup can also return HTTP 404 for an unknown source ID or name,
or 409 when a name matches multiple sources in the authenticated workspace.
Check both the request’s source_id and chunk overrides. Use a stored ID to
disambiguate, and see source lookup troubleshooting.
| Code | Description | Retryable |
|---|---|---|
agent_invocation_invalid | The tool invocation is incomplete or invalid. | No |
| 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 | Access to this MCP tool is denied. Please contact your administrator. | No |
mcp_tool_authorization_unavailable | MCP tool authorization is unavailable. Please contact your administrator. | Yes |
mcp_tool_approval_required | The MCP tool execution is waiting for approval. Please contact your administrator. | No |
Provider
Section titled “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
Section titled “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
Section titled “Validation”| Code | Description | Retryable |
|---|---|---|
invalid_argument | A request argument is invalid. | No |
validation_error | SDK input validation failed. | No |
Agentic governance and PDP
Section titled “Agentic governance and PDP”| Code | Description | Retryable |
|---|---|---|
agentic_error | The governed operation stopped safely. Please contact your administrator. | No |
governance_configuration_error | Agent governance is not fully configured. Please contact your administrator. | No |
guardrail_denied | Access to this operation is denied. Please contact your administrator. | No |
require_approval | This operation is waiting for approval. Please contact your administrator. | No |
mask_obligation_unsupported | A required data-protection obligation could not be applied safely. Please contact your administrator. | No |
gateway_unavailable | The Agentic gateway is unavailable. Please contact your administrator. | Yes |
invalid_gateway_response | The Agentic gateway returned an invalid response. Please contact your administrator. | Yes |
agent_registration_pending | Registration pending. Contact your administrator. | No |
agent_not_registered | Agent needs registration. Please contact your administrator. | No |
agent_registration_denied | This agent’s registration was denied. Please contact your administrator. | No |
registration_requester_mismatch | Registration refused: this agent is already being registered under a different email. Contact your administrator. | No |
agent_registration_not_ready | This agent’s registration review is incomplete. Please contact your administrator. | No |
agent_registration_approval_required | This agent requires registration approval. Please contact your administrator. | No |
agent_registration_quota_exceeded | The agent registration limit has been reached. Please contact your administrator. | No |
agent_name_required | This workload has no agent name, so it has no identity to govern. | No |
agent_name_conflict | This agent name is already associated with another credential. Please contact your administrator. | No |
agent_quarantined | This agent is quarantined pending code approval. Please contact your administrator. | No |
agent_registration_review_stale | The agent registration changed during review. Please contact your administrator. | No |
agent_registration_review_conflict | The agent registration changed during review. Please contact your administrator. | No |
agent_approval_pending | This operation is waiting for approval. Please contact your administrator. | No |
guardrail_approval_pending | This operation is waiting for approval. Please contact your administrator. | No |
approval_required | This operation is waiting for approval. Please contact your administrator. | No |
approval_access_denied | You are not allowed to review this approval. Please contact your administrator. | No |
approval_store_unavailable | The durable approval service is unavailable. Please contact your administrator. | Yes |
authz_store_unavailable | The authorization service is unavailable. Please contact your administrator. | Yes |
legacy_pdp_unavailable | The configured policy decision service is unavailable. Please contact your administrator. | Yes |
agent_blueprint_review_pending | This code blueprint is waiting for security review. Please contact your administrator. | No |
agent_blueprint_review_denied | This code blueprint was denied. Please contact your administrator. | No |
blueprint_scan_unavailable | The code blueprint could not be scanned safely. Please contact your administrator. | Yes |
blueprint_scan_required | An approved code blueprint is required. Please contact your administrator. | No |
blueprint_scanning_required | Static code-blueprint scanning must remain enabled. Please contact your administrator. | No |
blueprint_registration_failed | The code blueprint could not be registered safely. Please contact your administrator. | Yes |
blueprint_coverage_incomplete | Agent code verification is incomplete. Please contact your administrator. | No |
blueprint_manifest_too_large | The executable code blueprint exceeds the safe size limit. Please contact your administrator. | No |
blueprint_remote_tool_unverified | A remote tool could not be verified against an MCP connection. Please contact your administrator. | No |
blueprint_mcp_inventory_unavailable | The MCP tool inventory is unavailable. Please contact your administrator. | Yes |
blueprint_model_scan_pending | Code model analysis is still running. Please contact your administrator. | Yes |
blueprint_model_scan_failed | Code model analysis failed safely. Please contact your administrator. | Yes |
blueprint_model_unavailable | The configured code-analysis model is unavailable. Please contact your administrator. | Yes |
invalid_blueprint_manifest | The code blueprint evidence is invalid. Please contact your administrator. | No |
credential_configuration_error | The workload identity is not fully configured. Please contact your administrator. | No |
credential_provider_unsupported | The workload identity provider is unsupported. Please contact your administrator. | No |
credential_dependency_missing | A workload identity dependency is missing. | No |
credential_exchange_failed | The workload identity exchange failed. Please contact your administrator. | Yes |
credential_host_identity_missing | No Azure host identity is available to this process. | No |
credential_dpop_configuration_error | The issuer could not supply the required bound workload token. Please contact your administrator. | No |
credential_dpop_provider_unsupported | This credential adapter does not support DPoP token issuance. Please contact your administrator. | No |
credential_dpop_nonce_failed | The issuer’s DPoP nonce challenge could not be satisfied. Please contact your administrator. | Yes |
agent_task_context_invalid | The task mandate or its input references are invalid. | No |
agent_task_security_unavailable | The gateway cannot enforce the requested task mandate. Please contact your administrator. | No |
agent_task_receipt_required | A task writer authorization receipt is required. | No |
agent_workload_destination_invalid | The MCP request changed the configured workload authentication destination. | No |
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. Please contact your administrator. | No |
registry_discovery_unavailable | The agent discovery service is unavailable. Please contact your administrator. | Yes |
registry_unavailable | The agent registry is unavailable. Please contact your administrator. | Yes |
workload_proof_required | Agent identity verification is required. Please contact your administrator. | No |
agent_access_denied | Access to this operation is denied. Please contact your administrator. | No |
authorization_denied | Access to this operation is denied. Please contact your administrator. | No |
authz_engine_error | Access to this operation is denied. Please contact your administrator. | No |
context_deny | Access to this operation is denied. Please contact your administrator. | No |
no_store | Access to this operation is denied. Please contact your administrator. | No |
obo_action_not_allowed | Access to this operation is denied. Please contact your administrator. | No |
obo_delegation_required | Access to this operation is denied. Please contact your administrator. | No |
obo_no_acts_for | Access to this operation is denied. Please contact your administrator. | No |
obo_scope_mismatch | Access to this operation is denied. Please contact your administrator. | No |
obo_tool_not_allowed | Access to this operation is denied. Please contact your administrator. | No |
obo_user_lacks_perm | Access to this operation is denied. Please contact your administrator. | No |
obo_user_mismatch | Access to this operation is denied. Please contact your administrator. | No |
Agent runtime and managed execution
Section titled “Agent runtime and managed execution”| Code | Description | Retryable |
|---|---|---|
agent_runtime_configuration_error | Gateway runtime authentication is not configured consistently. | No |
agent_runtime_key_unavailable | The approved runtime signing key could not be loaded safely. | No |
agent_runtime_enrollment_pending | Registration pending. Contact your administrator. | No |
runtime_binding_identity_missing | The runtime key is bound to an agent whose identity has not been declared. Contact your administrator. | No |
managed_execution_unavailable | Server execution is unavailable. Please contact your administrator. | Yes |
managed_execution_bundle_unsupported | This script cannot be packaged for server execution. | No |
managed_execution_bundle_too_large | The server execution bundle exceeds its limit. | No |
managed_execution_dependency_missing | A script dependency cannot be pinned. | No |
managed_dependency_unavailable | A required package is not installed in the server runtime. Please contact your administrator. | No |
managed_python_version_unavailable | The required Python version is unavailable in the server runtime. Please contact your administrator. | No |
managed_execution_response_invalid | The server execution response is invalid. Please contact your administrator. | No |
managed_execution_output_unavailable | The saved execution output is unavailable. Please contact your administrator. | No |
managed_execution_submission_failed | The script could not be submitted for server execution. Please contact your administrator. | Yes |
managed_execution_configuration_invalid | The server worker configuration is incomplete. Please contact your administrator. | No |
managed_execution_context_unsupported | Server execution cannot transfer this requester or delegation context. | No |
managed_submission_changed | The submitted code or Python environment differs from the saved server run. Open the existing agent review to continue setup. | No |
managed_job_changed | The server run changed or conflicts with this submission. Refresh the existing agent review before continuing. | No |
managed_blueprint_changed | The saved server code differs from the current agent review. Please contact your administrator. | No |
managed_execution_pending | Server execution is pending. Your submission is saved. Please contact your administrator. | No |
managed_execution_identity_pending | Server identity verification is pending. Your submission is saved. Please contact your administrator. | No |
managed_execution_runtime_pending | Server runtime authorization is pending. Your submission is saved. Please contact your administrator. | No |
managed_execution_access_pending | Agent access setup is pending. Your submission is saved. Please contact your administrator. | No |
managed_execution_failed | Server execution failed. Please contact your administrator. | No |
managed_gateway_runtime_required | Server runs in this workspace need an agent identity that uses gateway exchange. Please contact your administrator. | No |
managed_execution_cancelled | Server execution was cancelled. Please contact your administrator. | No |
managed_execution_expired | The saved server run expired. Please contact your administrator. | No |
managed_execution_reconcile_required | The server run needs reconciliation before it can proceed. Please contact your administrator. | No |
agent_retired | This agent has been permanently retired. | No |
agent_runtime_binding_disabled | This runtime binding is not enabled. Please contact your administrator. | No |
agent_tool_scope_mismatch | This tool belongs to a different agent. Please contact your administrator. | No |
agent_tool_identity_review_required | Agent tool isolation requires review. Please contact your administrator. | No |
agent_runtime_exchange_failed | The gateway runtime session could not be obtained. Please contact your administrator. | Yes |
agent_runtime_response_invalid | The gateway returned an invalid or differently bound runtime session. Please contact your administrator. | No |
agent_runtime_assertion_invalid | The selected cloud runtime did not provide the required identity assertion. | No |
agent_runtime_request_proof_required | A runtime session requires a fresh proof for each request. | No |
agent_runtime_unavailable | Gateway runtime authentication is unavailable. Please contact your administrator. | Yes |
agent_runtime_authentication_failed | The runtime key or cloud identity does not match its approved binding. Please contact your administrator. | No |
agent_runtime_invalid | The runtime authentication request or binding is invalid. Please contact your administrator. | No |
agent_runtime_conflict | The runtime authentication configuration changed. Please contact your administrator. | Yes |
agent_runtime_capacity_exceeded | Runtime authentication capacity is temporarily exhausted. | Yes |
agent_lacks_perm | The agent lacks permission for this operation. Please contact your administrator. | No |
obo_agent_lacks_perm | The delegated agent lacks permission for this operation. Please contact your administrator. | No |
For administrator-resolved errors, action is “Please contact your
administrator.” The optional dashboard_path remains available as structured
metadata for administrative tooling; SDK client messages do not display it.
Use the catalog’s description for application messages and the stable code for
handling and protected diagnostics.