Error Codes

SotsAI uses stable, machine-readable error codes to help client systems handle failures predictably and safely.

Each error response includes:

a short error code
a category (authentication, quota, validation, etc.)
a human-readable message (for logs or debugging)

Error codes are consistent across endpoints and versions.

Why error codes matter

Error codes are designed for programmatic handling, not just display.

Typical use cases:

mapping errors to UI states or retry logic
structured logging and monitoring
enforcing fallback behavior in LLM pipelines
ensuring consistent behavior across microservices

You should rely on error codes, not message strings.

Error code endpoint

You can retrieve the full, up-to-date list of supported error codes via the API.

This is useful for:

building SDKs
validating integration assumptions
synchronizing error handling across systems

The response includes:

all known error codes
their categories
summary metadata (such as total count)

Error response format

When a request fails, the API returns a structured error object.

Typical shape:

{
  "status": "error",
  "error": {
    "code": "ORG_QUOTA_EXCEEDED",
    "message": "Monthly usage quota has been reached.",
    "category": "quota"
  }
}

Only the code field should be used for logic.

Error categories

Error codes are grouped into high-level categories to simplify handling.

Authentication & authorization

Errors related to API keys, authentication, or access control.

Examples:

missing or invalid API key
inactive or disabled organization
insufficient permissions

Typical handling:

stop retrying
surface configuration or access issues to operators

Organization & account status

Errors indicating that the organization is not in a valid state.

Examples:

organization not found
organization suspended or inactive

Typical handling:

block further calls
prompt administrative review

Quota & usage limits

Errors triggered when usage limits are reached.

Examples:

monthly quota exceeded
rate limit exceeded

Typical handling:

do not retry immediately
apply graceful degradation or fallback behavior
notify operators or users

Payload & validation errors

Errors caused by malformed or incomplete requests.

Examples:

missing required fields
invalid field formats
unsupported values

Typical handling:

fix request construction
do not retry without modification

Psychometric & profile errors

Errors related to psychometric data resolution (SotsAI DISC API).

Examples:

DISC profile not found
profile unavailable for the given user

Typical handling:

fall back to user-only reasoning
prompt the user to complete or link a profile

Internal & unexpected errors

Errors caused by unexpected processing failures.

Examples:

provider timeouts
internal service errors

Typical handling:

retry with backoff
log for investigation
apply safe fallback if retries fail

Example: defensive handling strategy

A typical integration pattern (pseudo-code):

if error.error_code in QUOTA_ERRORS:
    degrade_gracefully()
elif error.error_code in PAYLOAD_ERRORS:
    fix_request()
elif error.error_code in LLM_ERRORS:
    retry_with_backoff()
else:
    escalate()

This approach keeps client behavior predictable and resilient.

Stability guarantees

Error codes are stable identifiers
New codes may be added over time
Existing codes will not change meaning
Deprecated codes (if any) will be clearly documented

You should design your systems to:

handle unknown error codes safely
rely on categories for default behavior

In short

Error codes give you:

deterministic error handling
cleaner client logic
safer retries and fallbacks
better observability