Errors & Rate Limits

Public API errors

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

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

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:

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.

Distributor API errors

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

{
  "status": "error",
  "errorCode": "RATE_LIMITED",
  "message": "Too many requests for this API key."
}

Match on errorCode, not on message - messages can change. Common integration-relevant codes:

Partner and organization codes

The full enums and per-endpoint responses are in the Distributor v1 reference.

Rate limits

The REST APIs limit per API key. For the Public API, 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://api2.smao.ai/api/v1/assistants" \
  -H "Authorization: Bearer $SMAO_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.

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.

Distributor responses that pass authentication include Retry-After (seconds) for the current rate-limit window, even before the bucket is exhausted. On 429, sleep that long before retrying; X-RateLimit-Reset carries the same information as an absolute Unix timestamp. 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.

All three 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, the Distributor API rejects with 503 RATE_LIMIT_UNAVAILABLE, 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.