---
title: Errors
description: HTTP, JSON-RPC, authentication, rate-limit, and freshness errors.
type: troubleshooting
summary: Stable error bodies and recovery actions.
related:
  - /en/docs/api-keys
  - /en/docs/rest
  - /en/docs/mcp
  - /en/docs/operations
---

# Errors



AI Workflow MCP errors are intentionally small and machine-readable. Agents should branch on HTTP status for REST and JSON-RPC `error.code` for MCP.

## Authentication [#authentication]

Malformed key:

```http
HTTP/2 401
cache-control: no-store
```

```json
{
  "error": "invalid API key",
  "hint": "Use Authorization: Bearer ak_..."
}
```

Unknown, revoked, or deleted key:

```json
{
  "error": "invalid API key"
}
```

Expired key:

```json
{
  "error": "expired API key"
}
```

Recovery:

1. Confirm the key starts with `ak_`.
2. Confirm the request uses `Authorization: Bearer ${AIWORKFLOWMCP_API_KEY}`.
3. Create a new key from `https://aiworkflowmcp.com/en/account/api-keys/`.
4. Revoke old keys that may have leaked.

## REST Validation [#rest-validation]

Missing search query:

```json
{
  "error": "q is required"
}
```

Invalid type:

```json
{
  "allowed_types": [
    "DOC",
    "MCP_SERVER",
    "MODEL",
    "SKILL",
    "TOOL",
    "TUTORIAL"
  ],
  "error": "invalid type"
}
```

Unknown detail id:

```json
{
  "error": "model not found"
}
```

Equivalent detail errors exist for tools, skills, MCP servers, and frameworks.

## JSON-RPC Errors [#json-rpc-errors]

Invalid JSON:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "invalid JSON"
  }
}
```

Batch requests:

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "batch requests are not supported"
  }
}
```

Unknown method:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found: example"
  }
}
```

Tool execution failure:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "model_id is required"
  }
}
```

Recovery:

* Call `tools/list` and validate the tool name.
* Send an object in `params.arguments`.
* Use required argument names exactly as documented.
* Use concise English inputs for search tools.

## Rate Limit [#rate-limit]

Rate-limited calls return:

```http
HTTP/2 429
retry-after: 60
```

```json
{
  "error": "rate limit exceeded",
  "limit_per_minute": 120,
  "retry_after_seconds": 60
}
```

Authenticated keys use a higher per-minute limit. Back off for at least the `retry-after` value before retrying.

## Freshness [#freshness]

When `fresh_only=true` is set, search and tool paths can reject stale facts instead of returning older data. If a freshness-sensitive path fails:

1. Check `https://mcp.aiworkflowmcp.com/health`.
2. Check `https://api.aiworkflowmcp.com/v1/sources/status`.
3. Retry after source refresh if `stale_entities`, `source_errors`, or `source_refresh_due` are non-zero.
4. Drop `fresh_only=true` only for exploratory discovery where stale data is acceptable.

## Status Handling [#status-handling]

* `200`: request succeeded.
* `202`: accepted MCP signal or notification with no response body.
* `400`: invalid REST query or JSON-RPC request.
* `401`: API key problem.
* `404`: unknown detail resource or method.
* `429`: per-minute rate limit.
* `500`: unexpected service failure.


---

For a semantic overview of all documentation, see [/en/sitemap.md](/en/sitemap.md)

For an index of all available documentation, see [/en/llms.txt](/en/llms.txt)