Error Code Reference

All error responses share a consistent JSON envelope. Every error includes a machine-readable code so you can handle each failure case precisely, independent of HTTP status.

Error envelope

Standard (JSON) error envelope:

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Streaming errors arrive as SSE events:

text

data: {"type": "error", "code": "ERROR_CODE", "message": "..."}

Authentication errors

MISSING_API_KEY401AuthNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The X-Api-Key header was not included in the request.

Resolution

bash

X-Api-Key: sk-so-xxxxxxxxxxxxxxxx

INVALID_API_KEY401AuthNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The provided API key does not match any active user account. The key may be mistyped or truncated, the account may be deactivated, or the key was rotated.

Resolution

Double-check the key value in your .env or secrets store. Log in to the dashboard and verify your API key under Settings → API Key. Generate a new key if the old one was rotated or revoked.

Plan & quota errors

QUOTA_EXCEEDED429QuotaNot retryable

Endpoints: /v1/chat, /v1/chat/streamExtra fields: used, limit, upgrade_url

Why it happens

Your account has consumed all of its monthly API call quota.

Resolution

Wait for the quota to reset at the start of your next billing cycle, or upgrade your plan at the URL provided in upgrade_url.

RATE_LIMIT_EXCEEDED429Rate LimitRetryable

Endpoints: /v1/chat, /v1/chat/stream (shared counter)Extra fields: retry_after

Why it happens

The agent has exceeded its per-minute request rate limit (rate_limit_rpm). Both /v1/chat and /v1/chat/stream share the same per-agent counter. Starter plans default to 30 req/min, Pro plans to 50 req/min.

Resolution

Implement exponential backoff and retry after the number of seconds indicated in the X-RateLimit-Reset response header. Reduce request concurrency and cache responses where possible. See Rate Limits for full detail.

SUBSCRIPTION_CANCELED403PlanNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The account owner's subscription has been canceled. API access is disabled until the subscription is reactivated.

Resolution

Reactivate the subscription from Settings → Billing, or contact support if you believe this is an error.

PLAN_RESTRICTED403PlanNot retryable

Endpoints: /v1/chat/streamExtra fields: upgrade_url

Why it happens

The streaming endpoint requires a Pro or Enterprise plan. Your account is on the Starter plan.

Resolution

Upgrade your plan at the URL provided in upgrade_url, or use the non-streaming /v1/chat endpoint which is available on all plans.

Request validation errors

MISSING_AGENT_ID400ValidationNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

No agent ID was provided. The API requires an X-Agent-Id request header.

Resolution

Pass the agent UUID in the request header:

bash

X-Agent-Id: 736c5015-f67e-4fe5-9932-590d9048b014

MISSING_MESSAGE400ValidationNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The message field in the request body was empty or missing.

Resolution

json

{ "message": "Your question here" }

VALIDATION_ERROR422ValidationNot retryable

Endpoints: AllExtra fields: details (array of field-level errors)

Why it happens

The request body failed schema validation. Common causes: sending a non-JSON Content-Type, wrong field types (e.g. a number where a string is expected), or a completely empty body when fields are required.

Resolution

Check the details array in the error response — it lists each invalid field and the reason. Ensure you are sending Content-Type: application/json.

Agent errors

AGENT_NOT_FOUND404AgentNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

No agent exists with the provided ID in the database.

Resolution

Verify the agent UUID in the dashboard under Agents. Ensure you're targeting the correct environment — staging and production have separate databases and separate agent IDs.

AGENT_INACTIVE403AgentNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The agent exists but has been disabled (is_active = false). An is_active check is always performed against the database on every request — even if the agent config is otherwise cached.

Resolution

Re-enable the agent in Agents → Settings → Publish. If you believe this is an error, check whether the agent was deactivated by an admin or automated process.

LLM provider errors

These errors originate from the underlying AI provider (Anthropic, OpenAI, Gemini, Groq) configured on the agent, not from the SentientOne platform itself.

LLM_AUTH_ERROR502LLM ProviderNot retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The API key stored on the agent for its AI provider is invalid or has been revoked.

Resolution

Go to Agents → Settings → AI Provider and update the provider API key with a valid one. Contact support if you did not change the key.

LLM_RATE_LIMITED429LLM ProviderRetryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The AI provider is rate-limiting requests from the agent's API key. This is a provider-level limit, entirely separate from the SentientOne API rate limit.

Resolution

Retry after a short delay — provider limits typically reset within seconds to minutes. If this happens frequently, request a rate limit increase from your AI provider account, or distribute load across multiple agent configurations with different provider keys.

LLM_UNAVAILABLE503LLM ProviderRetryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The AI provider is temporarily unavailable or overloaded (Anthropic HTTP 529 overloaded or 503, OpenAI connection timeout / network failure).

Resolution

Retry with exponential backoff — provider outages are typically brief. Check the provider's status page: status.anthropic.com or status.openai.com.

LLM_ERROR502LLM ProviderMaybe retryable

Endpoints: /v1/chat, /v1/chat/stream

Why it happens

The AI provider returned an unexpected error — not a rate limit, auth, or availability issue. Common causes: unsupported model name, malformed tool/function definition, or a provider-side bug.

Resolution

Check the agent's configured model name is valid and available in your provider account. Review any custom tool definitions attached to the agent for schema issues. Contact support with your conversation_id so the underlying provider error can be investigated.

Server errors

INTERNAL_ERROR500ServerRetryable

Endpoints: All

Why it happens

An unexpected exception occurred that was not caught by a more specific error handler. This should not happen in normal operation.

Resolution

Retry the request — transient infrastructure issues may resolve on their own. If the error persists, contact support with: the conversation_id from a previous successful response, the full request payload, and the timestamp of the failing request.

Quick reference

Code	HTTP	Category	Retryable
`MISSING_API_KEY`	401	Auth	No— Fix the request
`INVALID_API_KEY`	401	Auth	No— Fix the key
`QUOTA_EXCEEDED`	429	Quota	No— Upgrade or wait for reset
`RATE_LIMIT_EXCEEDED`	429	Rate Limit	Yes— Back off and retry
`SUBSCRIPTION_CANCELED`	403	Plan	No— Reactivate subscription
`PLAN_RESTRICTED`	403	Plan	No— Upgrade plan
`MISSING_AGENT_ID`	400	Validation	No— Fix the request
`MISSING_MESSAGE`	400	Validation	No— Fix the request
`VALIDATION_ERROR`	422	Validation	No— Fix the request
`AGENT_NOT_FOUND`	404	Agent	No— Verify agent ID
`AGENT_INACTIVE`	403	Agent	No— Re-enable agent
`LLM_AUTH_ERROR`	502	LLM Provider	No— Fix provider key
`LLM_RATE_LIMITED`	429	LLM Provider	Yes— Retry with backoff
`LLM_UNAVAILABLE`	503	LLM Provider	Yes— Retry with backoff
`LLM_ERROR`	502	LLM Provider	Maybe— Contact support
`INTERNAL_ERROR`	500	Server	Yes— Retry, then contact support

Always read X-Trace-Id

Every response — success or error — carries an X-Trace-Id header. Paste it into Tracing or a support ticket to find the full request timeline in seconds.