> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# Errors

All non-GraphQL `/v1` HTTP routes return a consistent JSON error envelope for
non-2xx responses.

```json
{
  "error": "Human-readable error string",
  "code": "OPTIONAL_MACHINE_CODE"
}
```

`error` is the compatibility field and is always present. `code` is a stable
machine-readable classifier when available. New codes may be added during v0,
but existing code meanings should not change.

## Common Codes

| Status | Example code           | Meaning                                                       |
| ------ | ---------------------- | ------------------------------------------------------------- |
| `400`  | `INVALID_SCHEMA`       | Request shape or schema validation failed                     |
| `404`  | `TABLE_NOT_FOUND`      | Referenced table does not exist                               |
| `409`  | `IDEMPOTENCY_CONFLICT` | Same idempotency key was reused with a different request body |
| `429`  | `RATE_LIMITED`         | Hosted or runtime rate limit rejected the request             |
| `503`  | `ENGINE_NOT_READY`     | Engine is unavailable or still recovering                     |

## SDK Requirements

SDKs should preserve the raw response body, expose parsed `error` and `code`
helpers where possible, and include HTTP status, method, and path in exception
or error objects. SDKs must not log bearer tokens or idempotency keys at default
log levels.

## GraphQL Errors

GraphQL routes use a GraphQL `data` / `errors` envelope instead of the standard
TraceDB JSON error envelope.

```json
{
  "errors": [
    {
      "message": "Unsupported root field 'unknown'",
      "path": ["unknown"],
      "extensions": {
        "code": "TRACEDB_GRAPHQL_ERROR"
      }
    }
  ]
}
```

Native GraphQL `data` and `errors` may both be present when only part of the
operation fails.