# Errors & Rate Limits (https://docs.walido.it/docs/errors)

## Public API errors [#public-api-errors]

Every non-2xx response from `/api/v1` has this shape:

```json
{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}
```

| Code | HTTP | Meaning | Retry? |
|---|---|---|---|
| `validation_failed` | 400 | Request body or query parameters failed validation | No - fix the request. Check `details` |
| `unauthorized` | 401 | Missing or invalid API key | No - fix the key |
| `subscription_required` | 402 | A feature required by this endpoint is not enabled for the organization | No - upgrade the plan |
| `forbidden` | 403 | The API key's role lacks permission for this action | No - use a key with a broader role |
| `trial_exhausted` | 403 | Usage access refused: the trial minutes are used up. Assistant creation and knowledge-item and prompt writes are refused; existing data stays readable | No - start a subscription |
| `subscription_required` | 403 | Usage access refused: the organization has no active subscription, so assistant creation and knowledge-item and prompt writes are refused. The `402` form instead means a plan feature is missing | No - activate a subscription |
| `organization_access_required` | 403 | Usage access refused: the organization is being deleted or no longer available, or was blocked while the request ran | No - contact support |
| `organization_blocked` | 403 | The API key's organization is blocked; every request with its keys is refused | No - contact support |
| `not_found` | 404 | Resource does not exist (or belongs to another organization) | No - check the ID |
| `conflict` | 409 | Resource is in use or the operation would violate an invariant | No - resolve the conflict first |
| `outbound_target_blocked` | 409 | The exact outbound target is blocked for the selected assistant. Manage lists and assignments in Dashboard → Settings → Blocked callers; configuration is not exposed through the Public API | No - choose another target or change the Dashboard policy |
| `rate_limit_exceeded` | 429 | Rate limit exceeded, an outbound assistant is in cooldown, or the limiter is unavailable | Yes - use `Retry-After` when present; otherwise back off |
| `internal_error` | 500 | Unexpected server error; the operation did not complete | Reads: yes. Mutations: check resource state first |

### Validation details [#validation-details]

`validation_failed` responses carry an optional `details` array. Each entry has a
`path` (array of field names and array indices) and a `message`:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": [
      { "path": ["first_name"], "message": "\"first_name\" is required" },
      { "path": ["phone_numbers", 0], "message": "\"phone_numbers[0]\" must be a string" }
    ]
  }
}
```

Per-endpoint error responses are listed in the [Public API reference](/docs/public).

## MCP errors [#mcp-errors]

Authentication and entitlement failures happen before MCP dispatch and are
normal HTTP errors. `401` means the credential is missing or invalid; OAuth
clients use its `WWW-Authenticate` metadata to start authorization. `402
subscription_required` means the organization is not entitled - reconnecting
OAuth cannot fix it. `403` means the user or organization lifecycle blocks the
request (a blocked organization gets `ORGANIZATION_BLOCKED` for OAuth and API-key
credentials alike), `429` means retry after backoff, and `503` means OAuth configuration or
the current organization authorization context cannot be loaded.

Authentication failures have the body `{ "error": { "code", "errorCode",
"message" } }`. Branch on `errorCode`:

| errorCode | HTTP | `code` | Meaning / action |
|---|---|---|---|
| `TOKEN_MISSING` | 401 | `unauthorized` | No bearer credential. Send one |
| `TOKEN_INVALID` | 401 | `unauthorized` | The access token or API key is invalid or expired, or the token belongs to another host. Authorize again or replace the key |
| `TOKEN_INCOMPLETE` | 401 | `unauthorized` | The access token lacks its user, organization or instance. Reconnect the app |
| `USER_INACTIVE` | 403 | `forbidden` | The connected user no longer exists or is not active |
| `ACCOUNT_DELETION_IN_PROGRESS` | 403 | `forbidden` | The connected user account is being deleted |
| `ORGANIZATION_NOT_FOUND` | 403 | `forbidden` | The organization chosen at consent no longer exists. Reconnect and choose another |
| `ORGANIZATION_BLOCKED` | 403 | `forbidden` | The organization is blocked. Contact support |
| `ORGANIZATION_DELETION_IN_PROGRESS` | 403 | `forbidden` | The organization chosen at consent is being deleted |
| `INSTANCE_NOT_FOUND` | 403 | `forbidden` | The token's instance cannot be found for this user. Reconnect the app |
| `OIDC_NOT_CONFIGURED` | 503 | `temporarily_unavailable` | OAuth is not configured on this deployment. API keys keep working |
| `CONNECTOR_ORIGIN_UNAVAILABLE` | 503 | `temporarily_unavailable` | The OAuth connector for this host could not be resolved. Retry shortly |
| `ORGANIZATION_AUTHORIZATION_INVALID` | 503 | `temporarily_unavailable` | The user's role in the organization cannot be loaded: a temporary failure, or the user is no longer a member. Retry; if it persists, reconnect instead of retrying forever |

Once dispatch starts, tool validation and service errors are MCP tool results
with `isError: true` and the Public API `{ "error": { "code", "message",
"details?" } }` body. Branch on `code`, not localized `message`. A tool whose
product feature is not enabled for the organization returns
`feature_not_available`, where the Public API answers `402
subscription_required`; a scope or role refusal returns `forbidden`. See
[MCP setup and access rules](/docs/mcp).

## Rate limits [#rate-limits]

The Public API limits per API key. Matched operations return the three headers
once authentication and the feature gate succeed and the limiter has evaluated
the request. Authentication failures, the `402` feature gate, and unmatched
routes do not carry the complete header set:

```bash
curl -sD - -o /dev/null "https://api.walido.it/api/v1/assistants" \
  -H "Authorization: Bearer <your_api_key>"
```

```text
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1776902940
```

`X-RateLimit-Reset` is a Unix timestamp (seconds) of the window reset.

| API | Bucket | Limit |
|---|---|---|
| Public | `read` - authenticated documented GET operations | 1,000 / min default |
| Public | `write` - authenticated documented POST / PATCH / DELETE operations except POST `/calls` | 200 / min default |
| Public | `outbound_trigger` - POST `/calls` | 60 / hour default, plus one outbound call per assistant per 60 seconds |
| MCP | `read` - every message except calls of write tools or unknown tool names, including `initialize`, `tools/list` and notifications; per organization and OAuth user or API key | 1,000 / min default |
| MCP | `write` - calls of write tools or unknown tool names; per organization and OAuth user or API key | 200 / min default |

MCP counts every JSON-RPC message. A batch of N messages costs N units and is
charged to the write bucket when any message calls a write tool or an unknown
tool. A batch that does not fit is rejected whole with `429`, and none of its
messages run. A batch of more than 100 messages is rejected with `400` and
JSON-RPC error `-32600` after its units have been charged, so send at most 100
messages per batch.

A Public API `429` caused by the per-assistant outbound cooldown, including a storage failure while reserving it, does not include `Retry-After`; back off for at least 60 seconds.

Both surfaces fail closed. If the rate-limit store cannot be reached, the
Public API rejects with 429 `rate_limit_exceeded` plus the rate-limit headers and
`Retry-After: 30`, and MCP rejects with a 429 JSON-RPC error plus `Retry-After`. Retry with
exponential backoff; do not treat it as a hard failure. If the Public API
limiter itself fails before it can evaluate the bucket, for example because of
a misconfiguration, the `429` may carry neither the rate-limit headers nor
`Retry-After`.
