Error codes

Error response format

{
  "error": {
    "code": "QWED-001",
    "message": "Verification failed",
    "details": {
      "engine": "math",
      "reason": "Invalid expression syntax"
    }
  }
}

General errors

Code	HTTP	Message
`QWED-001`	400	Invalid request format
`QWED-002`	401	Invalid or missing API key
`QWED-003`	403	Access denied
`QWED-004`	404	Resource not found
`QWED-005`	429	Rate limit exceeded
`QWED-006`	500	Internal server error
`QWED-007`	503	Service temporarily unavailable

Verification errors

Code	Message
`QWED-100`	Unknown verification type
`QWED-101`	Query is empty
`QWED-102`	Query too long
`QWED-103`	Invalid expression syntax
`QWED-104`	Engine timeout
`QWED-105`	Unsupported language

Execution errors

Code	HTTP	Message
`QWED-300`	503	Secure execution runtime unavailable — the Docker sandbox is not reachable
`QWED-301`	403	Verification blocked by security policy

These errors apply to the /verify/stats and /verify/consensus endpoints. Statistical and consensus Python verification requires the secure Docker sandbox. When Docker is unavailable, the API returns 503 instead of falling back to in-process execution.

Security errors

Code	Message
`QWED-200`	Prompt injection detected
`QWED-201`	SQL injection detected
`QWED-202`	Dangerous code pattern
`QWED-203`	Blocked content

Agent errors

Code	Message
`QWED-AGENT-001`	Agent not registered
`QWED-AGENT-002`	Invalid agent token
`QWED-AGENT-003`	Agent suspended
`QWED-AGENT-004`	Action not permitted
`QWED-AGENT-ACTION-001`	Unknown `action_type` — no registered semantics for the requested action
`QWED-AGENT-BUDGET-001`	Daily cost limit exceeded
`QWED-AGENT-BUDGET-002`	Hourly rate limit exceeded

Agent context errors

New in v5.0.0

Code	Message
`QWED-AGENT-CTX-001`	Action context with `conversation_id` and `step_number` is required
`QWED-AGENT-CTX-002`	`step_number` must be >= 1

Agent action registration errors

New in v5.1.1

Code	Message
`QWED-AGENT-ACTION-001`	Unknown `action_type` cannot be verified without explicit registered semantics

Agent loop detection errors

New in v5.0.0

Code	Message
`QWED-AGENT-LOOP-001`	Conversation step limit exceeded (max 50 steps)
`QWED-AGENT-LOOP-002`	Replay or out-of-order action step detected
`QWED-AGENT-LOOP-003`	Repetitive action loop detected (same action more than 2 consecutive times)
`QWED-AGENT-LOOP-004`	No-progress doom loop detected — agent is repeating the same action on an unchanged world state (≥ 3 times in the sliding window)

Agent state errors

New in v5.1.0

These errors relate to the progress-aware doom loop guard (LOOP-004). They are returned when the pre_action_state_hash or state_source context fields are invalid.

Code	Message
`QWED-AGENT-STATE-001`	`pre_action_state_hash` and `state_source` must be provided together (or are required when `DOOM_LOOP_GUARD_REQUIRED` is enabled)
`QWED-AGENT-STATE-002`	`pre_action_state_hash` must be a 64-character lowercase hex SHA-256 digest
`QWED-AGENT-STATE-003`	`state_source` must be one of: `file_tree`, `db_snapshot`, `conversation_digest`, `git_tree`, `custom`
`QWED-AGENT-STATE-004`	Action parameters contain non-deterministic JSON-incompatible values

Attestation errors

Code	Message
`QWED-ATT-001`	Invalid attestation format
`QWED-ATT-002`	Attestation expired
`QWED-ATT-003`	Attestation revoked
`QWED-ATT-004`	Untrusted issuer
`QWED-ATT-005`	Signature verification failed

Exception hierarchy

The QWED SDK and server use a structured exception hierarchy that provides actionable error messages with suggestions and documentation links. All exceptions extend the base QWEDError class.

Base exception

All QWED exceptions include these fields:

Field	Type	Description
`message`	string	Human-readable error description
`suggestion`	string \| null	Actionable fix recommendation
`docs_url`	string	Link to relevant documentation
`details`	object	Additional context (engine, expression, etc.)

DSL and parsing exceptions

Exception	Trigger	Details
`QWEDSyntaxError`	Invalid DSL expression syntax	Includes `expression`, `line`, and `column` fields for precise error location
`QWEDSymbolNotFoundError`	Unknown variable or function in expression	Includes “did you mean?” suggestions from available symbols

Verification exceptions

Exception	Engine	Details
`QWEDVerificationError`	Any	Base class for all verification failures. Includes `expected`, `actual`, and `engine` fields
`QWEDMathError`	Math	Includes `expression`, `expected`, `calculated`, and `tolerance` values
`QWEDLogicError`	Logic	Includes `formula` and counterexample `model` when available
`QWEDCodeError`	Code	Includes `code`, `output`, `expected_output`, and `execution_error`
`QWEDSQLError`	SQL	Includes `query`, `schema`, and specific `issue` description

Configuration and API exceptions

Exception	Trigger	Details
`QWEDConfigError`	Invalid configuration	Includes `config_key`, `expected_type`, and `actual_value`
`QWEDAPIError`	API communication failure	Includes `status_code` and `endpoint`. Provides targeted suggestions per status code (401 = check API key, 429 = rate limit, etc.)
`QWEDDependencyError`	Missing package	Includes install command (e.g., `pip install sympy`)

Handling errors

Python

from qwed_sdk import QWEDClient, QWEDError

try:
    result = client.verify("test")
except QWEDError as e:
    print(f"Error: {e.message}")
    print(f"Suggestion: {e.suggestion}")
    print(f"Details: {e.details}")
    print(f"Docs: {e.docs_url}")

Catching specific exceptions

from qwed_sdk import QWEDClient
from qwed_new.core.exceptions import (
    QWEDMathError,
    QWEDSyntaxError,
    QWEDConfigError,
)

try:
    result = client.verify_math("invalid expression $$")
except QWEDSyntaxError as e:
    print(f"Syntax error at column {e.column}: {e.message}")
except QWEDMathError as e:
    print(f"Math error: expected {e.expected}, got {e.actual}")
except QWEDConfigError as e:
    print(f"Config issue with '{e.details.get('config_key')}': {e.message}")

TypeScript

import { QWEDError } from '@qwed-ai/sdk';

try {
  const result = await client.verify('test');
} catch (error) {
  if (error instanceof QWEDError) {
    console.log(`Error ${error.code}: ${error.message}`);
  }
}

API Reference

SDKs

Error response format

General errors

Verification errors

Execution errors

Security errors

Agent errors

Agent context errors

Agent action registration errors

Agent loop detection errors

Agent state errors

Attestation errors

Exception hierarchy

Base exception

DSL and parsing exceptions

Verification exceptions

Configuration and API exceptions

Handling errors

Python

Catching specific exceptions

TypeScript

​Error response format

​General errors

​Verification errors

​Execution errors

​Security errors

​Agent errors

​Agent context errors

​Agent action registration errors

​Agent loop detection errors

​Agent state errors

​Attestation errors

​Exception hierarchy

​Base exception

​DSL and parsing exceptions

​Verification exceptions

​Configuration and API exceptions

​Handling errors

​Python

​Catching specific exceptions

​TypeScript

Error response format

General errors

Verification errors

Execution errors

Security errors

Agent errors

Agent context errors

Agent action registration errors

Agent loop detection errors

Agent state errors

Attestation errors

Exception hierarchy

Base exception

DSL and parsing exceptions

Verification exceptions

Configuration and API exceptions

Handling errors

Python

Catching specific exceptions

TypeScript