> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/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#94-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}`);
  }
}
```