Error Codes

QWED API error code reference. Covers general errors (QWED-001 to QWED-007), verification errors (QWED-100+), and security errors with response format details.

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-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 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}`);
  }
}