Skip to Content
WalidoDocs

Errors & Rate Limits

Error envelopes and codes for MCP and the Public API, rate-limit buckets, and retry behavior.

Public API errors

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

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}
CodeHTTPMeaningRetry?
validation_failed400Request body or query parameters failed validationNo - fix the request. Check details
unauthorized401Missing or invalid API keyNo - fix the key
subscription_required402A feature required by this endpoint is not enabled for the organizationNo - upgrade the plan
forbidden403The API key's role lacks permission for this actionNo - use a key with a broader role
trial_exhausted403Usage access refused: the trial minutes are used up. Assistant creation and knowledge-item and prompt writes are refused; existing data stays readableNo - start a subscription
subscription_required403Usage 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 missingNo - activate a subscription
organization_access_required403Usage access refused: the organization is being deleted or no longer available, or was blocked while the request ranNo - contact support
organization_blocked403The API key's organization is blocked; every request with its keys is refusedNo - contact support
not_found404Resource does not exist (or belongs to another organization)No - check the ID
conflict409Resource is in use or the operation would violate an invariantNo - resolve the conflict first
outbound_target_blocked409The 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 APINo - choose another target or change the Dashboard policy
rate_limit_exceeded429Rate limit exceeded, an outbound assistant is in cooldown, or the limiter is unavailableYes - use Retry-After when present; otherwise back off
internal_error500Unexpected server error; the operation did not completeReads: yes. Mutations: check resource state first

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:

{
  "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.

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:

errorCodeHTTPcodeMeaning / action
TOKEN_MISSING401unauthorizedNo bearer credential. Send one
TOKEN_INVALID401unauthorizedThe access token or API key is invalid or expired, or the token belongs to another host. Authorize again or replace the key
TOKEN_INCOMPLETE401unauthorizedThe access token lacks its user, organization or instance. Reconnect the app
USER_INACTIVE403forbiddenThe connected user no longer exists or is not active
ACCOUNT_DELETION_IN_PROGRESS403forbiddenThe connected user account is being deleted
ORGANIZATION_NOT_FOUND403forbiddenThe organization chosen at consent no longer exists. Reconnect and choose another
ORGANIZATION_BLOCKED403forbiddenThe organization is blocked. Contact support
ORGANIZATION_DELETION_IN_PROGRESS403forbiddenThe organization chosen at consent is being deleted
INSTANCE_NOT_FOUND403forbiddenThe token's instance cannot be found for this user. Reconnect the app
OIDC_NOT_CONFIGURED503temporarily_unavailableOAuth is not configured on this deployment. API keys keep working
CONNECTOR_ORIGIN_UNAVAILABLE503temporarily_unavailableThe OAuth connector for this host could not be resolved. Retry shortly
ORGANIZATION_AUTHORIZATION_INVALID503temporarily_unavailableThe 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.

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:

curl -sD - -o /dev/null "https://api.walido.it/api/v1/assistants" \
  -H "Authorization: Bearer <your_api_key>"
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1776902940

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

APIBucketLimit
Publicread - authenticated documented GET operations1,000 / min default
Publicwrite - authenticated documented POST / PATCH / DELETE operations except POST /calls200 / min default
Publicoutbound_trigger - POST /calls60 / hour default, plus one outbound call per assistant per 60 seconds
MCPread - every message except calls of write tools or unknown tool names, including initialize, tools/list and notifications; per organization and OAuth user or API key1,000 / min default
MCPwrite - calls of write tools or unknown tool names; per organization and OAuth user or API key200 / 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.

On this page