GET /v1/error_codes

Return the full list of standardized SotsAI error codes, grouped by category.

This endpoint is primarily intended for:

• SDKs and client libraries
• integration tests and validation
• building robust error-handling maps

For conceptual guidance on categories and handling strategy, see: → Error Codes (Concept & Usage)

---

Endpoint

GET https://sil-api.sotsai.co/v1/error_codes

Auth

Send your organization API key in X-Sotsai-Api-Key.
Never expose this key to browsers or LLMs.

Rate limits

30/min per API key (organization).
Exceeding this limit returns 429.

Headers

Header	Required	Value
X-Sotsai-Api-Key	yes	sotsai_...
Content-Type	no	(not required for GET)

---

Request

This endpoint takes no request body.

Optional query parameters may be added in future versions; clients should ignore unknown fields in responses.

---

Example request

curl

curl -X GET "https://sil-api.sotsai.co/v1/error_codes" \
  -H "X-Sotsai-Api-Key: <YOUR_API_KEY>"

TypeScript

// Server-side only. Do NOT expose X-Sotsai-Api-Key in client apps.

const res = await fetch("https://sil-api.sotsai.co/v1/error_codes", {
  method: "GET",
  headers: {
    "X-Sotsai-Api-Key": process.env.SOTSAI_API_KEY!,
  },
});

const json = await res.json();

Python

# Server-side only. Do NOT expose X-Sotsai-Api-Key in client apps.

import os
import requests

resp = requests.get(
    "https://sil-api.sotsai.co/v1/error_codes",
    headers={"X-Sotsai-Api-Key": os.environ["SOTSAI_API_KEY"]},
    timeout=15,
)

resp.raise_for_status()
data = resp.json()

Responses

Status codes

Status	Meaning
200	OK
401	Missing or invalid API key
403	Organization inactive / forbidden
429	Rate limited
500	Internal error

Tip

For all API endpoints, failed requests return a stable error_code. Use error codes for logic — not message strings.

Success response 200

Example response body

{
  "status": "ok",
  "total": 42,
  "codes": [
    "ADVICE_GENERATION_FAILED",
    "ADVICE_GENERATION_INTERNAL_ERROR",
    "ADVICE_GENERATION_TIMEOUT",
    "ADVICE_MALFORMED",
    "ADMIN_EMAIL_ALREADY_USED",
    "ADMIN_NOT_FOUND",
    "API_KEY_CREATION_ERROR",
    "API_KEY_NOT_FOUND",
    "API_KEY_REVOKED",
    "BILLING_PORTAL_FAILED",
    "CANNOT_REMOVE_LAST_ADMIN",
    "CANNOT_REMOVE_SELF",
    "CONTRACT_NOT_FOUND",
    "INTERNAL_ERROR",
    "INVALID_API_KEY",
    "INVALID_PAYLOAD",
    "INVALID_PROFILE_PAYLOAD",
    "INVALID_SUMMARY_CONTEXT",
    "LIMIT_REACHED",
    "MISSING_FIELD",
    "NO_BILLING_CUSTOMER",
    "NO_VALID_ASSESSMENT",
    "ORG_BILLING_CUSTOMER_MISSING",
    "ORG_BILLING_INACTIVE",
    "ORG_INACTIVE",
    "ORG_INVITE_FAILED",
    "ORG_NOT_FOUND",
    "ORG_QUOTA_EXCEEDED",
    "ORG_READONLY",
    "PLAN_NOT_ALLOWED",
    "PROFILE_NOT_FOUND",
    "PSY_CONTRACT_NOT_FOUND",
    "PSY_CREDITS_MIN_PURCHASE",
    "PSY_INVITE_ALREADY_USED",
    "PSY_INVITE_EXPIRED",
    "PSY_INVITE_INVALID",
    "PSY_INVITE_NO_EMAILS",
    "PSY_INVITE_TOO_MANY_EMAILS",
    "PSY_INVITE_TOOL_MISMATCH",
    "PSY_LOCALE_NOT_SUPPORTED",
    "PSY_NOT_ENOUGH_CREDITS",
    "PSY_PROFILE_NOT_FOUND",
    "UNRESOLVED_INTERLOCUTOR",
    "UNSUPPORTED_ASSESSMENT_TYPE"
  ],
  "categories": {
    "auth": [
      "ADMIN_EMAIL_ALREADY_USED",
      "ADMIN_NOT_FOUND",
      "API_KEY_REVOKED",
      "CANNOT_REMOVE_LAST_ADMIN",
      "CANNOT_REMOVE_SELF",
      "INVALID_API_KEY",
      "ORG_INACTIVE",
      "ORG_INVITE_FAILED",
      "ORG_NOT_FOUND"
    ],
    "quota": [
      "LIMIT_REACHED",
      "ORG_BILLING_INACTIVE",
      "ORG_QUOTA_EXCEEDED",
      "ORG_READONLY",
      "PLAN_NOT_ALLOWED",
      "PSY_CREDITS_MIN_PURCHASE"
    ],
    "payload": [
      "API_KEY_CREATION_ERROR",
      "API_KEY_NOT_FOUND",
      "INVALID_PAYLOAD",
      "INVALID_PROFILE_PAYLOAD",
      "INVALID_SUMMARY_CONTEXT",
      "MISSING_FIELD",
      "UNSUPPORTED_ASSESSMENT_TYPE"
    ],
    "business": [
      "BILLING_PORTAL_FAILED",
      "CONTRACT_NOT_FOUND",
      "NO_BILLING_CUSTOMER",
      "NO_VALID_ASSESSMENT",
      "ORG_BILLING_CUSTOMER_MISSING",
      "PROFILE_NOT_FOUND",
      "PSY_CONTRACT_NOT_FOUND",
      "UNRESOLVED_INTERLOCUTOR"
    ],
    "advice": [
      "ADVICE_GENERATION_FAILED",
      "ADVICE_GENERATION_INTERNAL_ERROR",
      "ADVICE_GENERATION_TIMEOUT",
      "ADVICE_MALFORMED"
    ],
    "assessments": [
      "PSY_INVITE_ALREADY_USED",
      "PSY_INVITE_EXPIRED",
      "PSY_INVITE_INVALID",
      "PSY_INVITE_NO_EMAILS",
      "PSY_INVITE_TOO_MANY_EMAILS",
      "PSY_INVITE_TOOL_MISMATCH",
      "PSY_LOCALE_NOT_SUPPORTED",
      "PSY_NOT_ENOUGH_CREDITS",
      "PSY_PROFILE_NOT_FOUND"
    ],
    "internal": [
      "INTERNAL_ERROR"
    ]
  }
}

Caution

The /error_codes endpoint intentionally returns codes only.

• Error codes are stable, machine-readable identifiers
• No human-readable messages are exposed by default
• Client systems are expected to:
  • map codes to internal messages
  • localize or rephrase as needed
  • apply fallback logic by category

This design prevents data leakage, avoids brittle string matching, and keeps error handling deterministic in LLM pipelines.

Error response (shape)

Example error response body

{
  "status": "error",
  "error_code": "API_KEY_INVALID",
  "message": "Invalid API key."
}

Notes

Stability guarantees

• Error codes are stable identifiers.
• New codes may be added over time.
• Existing codes will not change meaning.

Design clients to:

• handle unknown codes safely
• use categories as a default routing mechanism

Logging and privacy

Avoid logging:

• API keys
• raw user content from upstream systems

Safe to log:

• HTTP status
• latency
• returned error_code