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, 429 means retry after backoff, and 503 means OAuth configuration or the current organization authorization context cannot be loaded.

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. 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 after authentication, the feature gate, and the limiter succeed. Authentication failures, the 402 feature gate, unmatched routes, and a limiter-storage failure 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.

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 or an unavailable limiter store does not include Retry-After; use exponential backoff, with at least 60 seconds for the assistant cooldown.

All three surfaces fail closed. If the rate-limit store cannot be reached, the Public API rejects with 429 rate_limit_exceeded without rate-limit headers, 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.