Skip to content

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,
},
)
raise

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,
)
FieldUse
codeStable lowercase identifier for program logic.
descriptionCatalog-controlled, display-safe summary.
retryableCatalog hint; your application still decides whether and how to retry.
detailsStructured caller/request context such as status_code, stage, or the bounded original response_code. Review it before displaying or logging it.
status_codeHTTP status when the failure came from a gateway response.
messageRaw diagnostic text. Treat it as untrusted and potentially sensitive.
payloadRaw 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.

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

BoundaryPreserved type examples
Network/timeouthttpx.HTTPError, httpx.TimeoutException
Optional provider/framework dependencyImportError
Invalid environment valueValueError
Unsupported RAG wrapper targetTypeError
Unknown framework binder or operationValueError, AttributeError
Agentic application boundaryPermissionError, 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.

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)
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.

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.

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 aliasStable SDK code
unauthenticated, authentication_error, unauthorizedauthentication_failed
forbiddenpermission_denied
not_foundresource_not_found
rate_limit_exceeded, too_many_requestsrate_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.

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-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.

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.

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.

CodeDescriptionRetryable
sdk_errorThe DeepIntShield SDK operation failed.No
client_closedThe DeepIntShield client has already been closed.No
CodeDescriptionRetryable
configuration_errorThe SDK configuration is invalid or incomplete.No
virtual_key_missingAn active workspace Virtual Key is required.No
optional_dependency_missingA required optional dependency is not installed.No
feature_lockedThis feature is not enabled for the workspace. Please contact your administrator.No
CodeDescriptionRetryable
transport_errorThe gateway could not be reached.Yes
transport_timeoutThe gateway request timed out.Yes
http_errorThe gateway rejected the request.No
invalid_responseThe gateway returned an invalid response.Yes
authentication_failedGateway authentication failed. Please contact your administrator.No
permission_deniedThe requested gateway operation is not permitted. Please contact your administrator.No
resource_not_foundThe requested gateway resource was not found.No
conflictThe request conflicts with the current gateway state.No
rate_limitedThe gateway rate limit was exceeded.Yes
quota_exceededThe workspace quota was exceeded. Please contact your administrator.No
server_errorThe gateway failed to process the request.Yes
internal_errorThe gateway encountered an internal error.Yes
CodeDescriptionRetryable
chat_request_failedThe chat completion request failed.No
chat_stream_invalid_eventThe chat stream returned a malformed event.No
CodeDescriptionRetryable
guardrail_evaluation_failedThe guardrail evaluation failed.No
guardrail_blockedA guardrail blocked the operation. Please contact your administrator.No
CodeDescriptionRetryable
rag_evaluation_failedThe RAG security evaluation failed.No
rag_retriever_unsupportedThe retriever exposes no supported retrieval method.No
rag_embedder_unsupportedThe 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.

CodeDescriptionRetryable
agent_invocation_invalidThe tool invocation is incomplete or invalid.No
CodeDescriptionRetryable
mcp_dependency_missingA supported official MCP Python SDK is not available.No
mcp_connection_failedThe MCP server connection failed.No
mcp_protocol_errorThe MCP server returned an invalid protocol response.No
mcp_execution_failedThe MCP tool execution failed.No
mcp_discovery_failedMCP tool discovery failed.No
mcp_tool_name_invalidThe MCP tool name is not qualified with a server prefix.No
mcp_arguments_invalidThe MCP tool arguments are not valid JSON.No
mcp_tool_authorization_deniedAccess to this MCP tool is denied. Please contact your administrator.No
mcp_tool_authorization_unavailableMCP tool authorization is unavailable. Please contact your administrator.Yes
mcp_tool_approval_requiredThe MCP tool execution is waiting for approval. Please contact your administrator.No
CodeDescriptionRetryable
provider_dependency_missingThe selected provider dependency is not installed.No
provider_initialization_failedThe selected provider could not be initialized.No
CodeDescriptionRetryable
framework_binder_not_foundThe requested framework binder is not supported.No
framework_binder_attribute_missingThe framework does not provide the requested binder operation.No
framework_dependency_missingThe selected agent framework dependency is missing.No
framework_integration_unsupportedThe installed agent framework version is not supported.No
CodeDescriptionRetryable
invalid_argumentA request argument is invalid.No
validation_errorSDK input validation failed.No
CodeDescriptionRetryable
agentic_errorThe governed operation stopped safely. Please contact your administrator.No
governance_configuration_errorAgent governance is not fully configured. Please contact your administrator.No
guardrail_deniedAccess to this operation is denied. Please contact your administrator.No
require_approvalThis operation is waiting for approval. Please contact your administrator.No
mask_obligation_unsupportedA required data-protection obligation could not be applied safely. Please contact your administrator.No
gateway_unavailableThe Agentic gateway is unavailable. Please contact your administrator.Yes
invalid_gateway_responseThe Agentic gateway returned an invalid response. Please contact your administrator.Yes
agent_registration_pendingRegistration pending. Contact your administrator.No
agent_not_registeredAgent needs registration. Please contact your administrator.No
agent_registration_deniedThis agent’s registration was denied. Please contact your administrator.No
registration_requester_mismatchRegistration refused: this agent is already being registered under a different email. Contact your administrator.No
agent_registration_not_readyThis agent’s registration review is incomplete. Please contact your administrator.No
agent_registration_approval_requiredThis agent requires registration approval. Please contact your administrator.No
agent_registration_quota_exceededThe agent registration limit has been reached. Please contact your administrator.No
agent_name_requiredThis workload has no agent name, so it has no identity to govern.No
agent_name_conflictThis agent name is already associated with another credential. Please contact your administrator.No
agent_quarantinedThis agent is quarantined pending code approval. Please contact your administrator.No
agent_registration_review_staleThe agent registration changed during review. Please contact your administrator.No
agent_registration_review_conflictThe agent registration changed during review. Please contact your administrator.No
agent_approval_pendingThis operation is waiting for approval. Please contact your administrator.No
guardrail_approval_pendingThis operation is waiting for approval. Please contact your administrator.No
approval_requiredThis operation is waiting for approval. Please contact your administrator.No
approval_access_deniedYou are not allowed to review this approval. Please contact your administrator.No
approval_store_unavailableThe durable approval service is unavailable. Please contact your administrator.Yes
authz_store_unavailableThe authorization service is unavailable. Please contact your administrator.Yes
legacy_pdp_unavailableThe configured policy decision service is unavailable. Please contact your administrator.Yes
agent_blueprint_review_pendingThis code blueprint is waiting for security review. Please contact your administrator.No
agent_blueprint_review_deniedThis code blueprint was denied. Please contact your administrator.No
blueprint_scan_unavailableThe code blueprint could not be scanned safely. Please contact your administrator.Yes
blueprint_scan_requiredAn approved code blueprint is required. Please contact your administrator.No
blueprint_scanning_requiredStatic code-blueprint scanning must remain enabled. Please contact your administrator.No
blueprint_registration_failedThe code blueprint could not be registered safely. Please contact your administrator.Yes
blueprint_coverage_incompleteAgent code verification is incomplete. Please contact your administrator.No
blueprint_manifest_too_largeThe executable code blueprint exceeds the safe size limit. Please contact your administrator.No
blueprint_remote_tool_unverifiedA remote tool could not be verified against an MCP connection. Please contact your administrator.No
blueprint_mcp_inventory_unavailableThe MCP tool inventory is unavailable. Please contact your administrator.Yes
blueprint_model_scan_pendingCode model analysis is still running. Please contact your administrator.Yes
blueprint_model_scan_failedCode model analysis failed safely. Please contact your administrator.Yes
blueprint_model_unavailableThe configured code-analysis model is unavailable. Please contact your administrator.Yes
invalid_blueprint_manifestThe code blueprint evidence is invalid. Please contact your administrator.No
credential_configuration_errorThe workload identity is not fully configured. Please contact your administrator.No
credential_provider_unsupportedThe workload identity provider is unsupported. Please contact your administrator.No
credential_dependency_missingA workload identity dependency is missing.No
credential_exchange_failedThe workload identity exchange failed. Please contact your administrator.Yes
credential_host_identity_missingNo Azure host identity is available to this process.No
credential_dpop_configuration_errorThe issuer could not supply the required bound workload token. Please contact your administrator.No
credential_dpop_provider_unsupportedThis credential adapter does not support DPoP token issuance. Please contact your administrator.No
credential_dpop_nonce_failedThe issuer’s DPoP nonce challenge could not be satisfied. Please contact your administrator.Yes
agent_task_context_invalidThe task mandate or its input references are invalid.No
agent_task_security_unavailableThe gateway cannot enforce the requested task mandate. Please contact your administrator.No
agent_task_receipt_requiredA task writer authorization receipt is required.No
agent_workload_destination_invalidThe MCP request changed the configured workload authentication destination.No
agent_decision_context_missingThe Agentic decision context is incomplete.No
principal_identifier_missingA stable principal identity is required.No
registry_discovery_emptyNo discoverable agent topology was provided.No
registry_discovery_invalidThe agent discovery payload is invalid.No
registry_discovery_pendingAgent discovery is already in progress.Yes
registry_discovery_rejectedThe agent registry rejected the discovery report. Please contact your administrator.No
registry_discovery_unavailableThe agent discovery service is unavailable. Please contact your administrator.Yes
registry_unavailableThe agent registry is unavailable. Please contact your administrator.Yes
workload_proof_requiredAgent identity verification is required. Please contact your administrator.No
agent_access_deniedAccess to this operation is denied. Please contact your administrator.No
authorization_deniedAccess to this operation is denied. Please contact your administrator.No
authz_engine_errorAccess to this operation is denied. Please contact your administrator.No
context_denyAccess to this operation is denied. Please contact your administrator.No
no_storeAccess to this operation is denied. Please contact your administrator.No
obo_action_not_allowedAccess to this operation is denied. Please contact your administrator.No
obo_delegation_requiredAccess to this operation is denied. Please contact your administrator.No
obo_no_acts_forAccess to this operation is denied. Please contact your administrator.No
obo_scope_mismatchAccess to this operation is denied. Please contact your administrator.No
obo_tool_not_allowedAccess to this operation is denied. Please contact your administrator.No
obo_user_lacks_permAccess to this operation is denied. Please contact your administrator.No
obo_user_mismatchAccess to this operation is denied. Please contact your administrator.No
CodeDescriptionRetryable
agent_runtime_configuration_errorGateway runtime authentication is not configured consistently.No
agent_runtime_key_unavailableThe approved runtime signing key could not be loaded safely.No
agent_runtime_enrollment_pendingRegistration pending. Contact your administrator.No
runtime_binding_identity_missingThe runtime key is bound to an agent whose identity has not been declared. Contact your administrator.No
managed_execution_unavailableServer execution is unavailable. Please contact your administrator.Yes
managed_execution_bundle_unsupportedThis script cannot be packaged for server execution.No
managed_execution_bundle_too_largeThe server execution bundle exceeds its limit.No
managed_execution_dependency_missingA script dependency cannot be pinned.No
managed_dependency_unavailableA required package is not installed in the server runtime. Please contact your administrator.No
managed_python_version_unavailableThe required Python version is unavailable in the server runtime. Please contact your administrator.No
managed_execution_response_invalidThe server execution response is invalid. Please contact your administrator.No
managed_execution_output_unavailableThe saved execution output is unavailable. Please contact your administrator.No
managed_execution_submission_failedThe script could not be submitted for server execution. Please contact your administrator.Yes
managed_execution_configuration_invalidThe server worker configuration is incomplete. Please contact your administrator.No
managed_execution_context_unsupportedServer execution cannot transfer this requester or delegation context.No
managed_submission_changedThe submitted code or Python environment differs from the saved server run. Open the existing agent review to continue setup.No
managed_job_changedThe server run changed or conflicts with this submission. Refresh the existing agent review before continuing.No
managed_blueprint_changedThe saved server code differs from the current agent review. Please contact your administrator.No
managed_execution_pendingServer execution is pending. Your submission is saved. Please contact your administrator.No
managed_execution_identity_pendingServer identity verification is pending. Your submission is saved. Please contact your administrator.No
managed_execution_runtime_pendingServer runtime authorization is pending. Your submission is saved. Please contact your administrator.No
managed_execution_access_pendingAgent access setup is pending. Your submission is saved. Please contact your administrator.No
managed_execution_failedServer execution failed. Please contact your administrator.No
managed_gateway_runtime_requiredServer runs in this workspace need an agent identity that uses gateway exchange. Please contact your administrator.No
managed_execution_cancelledServer execution was cancelled. Please contact your administrator.No
managed_execution_expiredThe saved server run expired. Please contact your administrator.No
managed_execution_reconcile_requiredThe server run needs reconciliation before it can proceed. Please contact your administrator.No
agent_retiredThis agent has been permanently retired.No
agent_runtime_binding_disabledThis runtime binding is not enabled. Please contact your administrator.No
agent_tool_scope_mismatchThis tool belongs to a different agent. Please contact your administrator.No
agent_tool_identity_review_requiredAgent tool isolation requires review. Please contact your administrator.No
agent_runtime_exchange_failedThe gateway runtime session could not be obtained. Please contact your administrator.Yes
agent_runtime_response_invalidThe gateway returned an invalid or differently bound runtime session. Please contact your administrator.No
agent_runtime_assertion_invalidThe selected cloud runtime did not provide the required identity assertion.No
agent_runtime_request_proof_requiredA runtime session requires a fresh proof for each request.No
agent_runtime_unavailableGateway runtime authentication is unavailable. Please contact your administrator.Yes
agent_runtime_authentication_failedThe runtime key or cloud identity does not match its approved binding. Please contact your administrator.No
agent_runtime_invalidThe runtime authentication request or binding is invalid. Please contact your administrator.No
agent_runtime_conflictThe runtime authentication configuration changed. Please contact your administrator.Yes
agent_runtime_capacity_exceededRuntime authentication capacity is temporarily exhausted.Yes
agent_lacks_permThe agent lacks permission for this operation. Please contact your administrator.No
obo_agent_lacks_permThe 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.