> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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

<Info>New in v5.0.0</Info>

| 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

<Info>New in v5.1.1</Info>

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

## Agent loop detection errors

<Info>New in v5.0.0</Info>

| 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

<Info>New in v5.1.0</Info>

These errors relate to the progress-aware doom loop guard ([LOOP-004](/specs/agent#9-4-progress-aware-doom-loop-detection-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

```python theme={null}
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

```python theme={null}
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

```typescript theme={null}
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}`);
  }
}
```


## Related topics

- [AgentStateGuard: verify agent state before commit](/advanced/agent-state-guard.md)
- [MCP tools reference](/mcp/tools.md)
- [Changelog Archive](/changelog-archive.md)
- [Prompt injection defense and QWED security hardening](/advanced/security-hardening.md)
- [QWED MCP troubleshooting](/mcp/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.