Quota exceeded

This issue occurs when your organization has reached a usage or billing limit.

Quota errors are expected operational states, not system failures.

Your integration should handle them gracefully and predictably.

What this means

SotsAI rejected the request because one of the following limits was reached:

monthly usage quota
plan restriction
organization is in read-only or billing-inactive state
rate limit exceeded

Common error codes include:

ORG_QUOTA_EXCEEDED
PLAN_NOT_ALLOWED
LIMIT_REACHED
ORG_BILLING_INACTIVE
ORG_READONLY

Typical symptoms

You may observe:

/v1/advice returns a quota-related error
repeated failures despite valid payloads
advice suddenly stops working while other features still work
errors appear at predictable volume thresholds

Why this happens

1) Monthly quota reached

The most common cause.

your organization has consumed its allocated quota
usage resets on the next billing cycle
further calls are blocked

This is normal behavior.

2) Plan does not allow this feature

Your plan may:

restrict certain endpoints
limit psychometric-powered reasoning
enforce read-only behavior

3) Billing inactive or misconfigured

Examples:

payment failed
billing customer missing
contract inactive
organization in read-only mode

In this case, quota errors protect the system from uncontrolled usage.

4) Rate limit exceeded

Less common, but possible.

bursts of traffic
retry loops without backoff
misconfigured orchestration

Rate limits are short-lived and usually recover automatically.

How to handle it (recommended behavior)

Rule #1: Do NOT retry blindly

Quota-related errors should not trigger automatic retries.

Retries will:

fail again
waste resources
increase load
degrade UX

Rule #2: Degrade gracefully

When quota is exceeded:

skip the SotsAI call
let your LLM handle the request autonomously
return a reasonable, non-personalized response

Example behavior:

“Advanced behavioral adaptation is temporarily unavailable.”

This preserves continuity without breaking the user experience.

Rule #3: Surface the right signal

Who should see what?

End users

should not see billing errors
should get a neutral experience

Operators / admins

should be notified
should see quota status
should know how to resolve it

Recommended orchestration pattern

Call SotsAI
↓
IF success:
  apply behavioral reasoning
ELSE IF quota error:
  skip SotsAI
  fallback to LLM-only behavior
  log quota event
ELSE:
  handle according to error category

What NOT to do

Avoid these anti-patterns:

❌ retrying quota errors
❌ blocking the entire feature
❌ exposing billing errors to end users
❌ silently swallowing the issue without logging

Quota exhaustion should be visible to operators, not users.

How to resolve quota issues

Depending on the cause:

upgrade or adjust the plan
wait for quota reset
resolve billing issues
reduce unnecessary calls
improve orchestration gating

Debugging checklist

When quota errors appear, check:

If usage spikes unexpectedly, investigate:

missing profile gating
repeated retries
calling SotsAI for non-interpersonal requests