Errors

The iCog API uses conventional HTTP status codes and a single, predictable JSON error shape. A 2xx status means success. A 4xx means something about your request was wrong (auth, validation, quota, or a missing resource). A 5xx means the request was valid but iCog or one of its dependencies failed.

Base URL for all endpoints is https://api.cognitivx.io. See Authentication for how to pass a key.

Error shape

Every error response is JSON with a detail field. detail is usually a string:

{
  "detail": "Memory not found"
}

For a few gated and quota errors (403 and 429), detail is a structured object instead of a string. Those shapes are documented per status code below. Always check whether detail is a string or an object before reading it.

Uncaught server errors are wrapped by a global handler, so even a 500 is valid JSON, never a plain-text stack trace or an HTML page:

{
  "detail": "Internal server error",
  "path": "/api/remember"
}

Validation errors (422)

When a request body or query parameter fails schema validation, FastAPI returns 422 Unprocessable Entity. Here detail is an array of field errors, not a string:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

A 422 also fires when a path parameter that must be a UUID (such as a memory_id) cannot be parsed. Validation errors are not retryable: fix the request and send it again.

Status codes

These are the status codes the API actually returns and what triggers each one.

401 Unauthorized

Returned when credentials are missing or invalid. detail is a string, and the response carries a WWW-Authenticate: Bearer header when a token failed to validate.

{
  "detail": "Could not validate credentials"
}

Common detail strings: Invalid API key, Could not validate credentials, and Token expired. Fix the credential rather than retrying. If you are using a short-lived JWT, mint or refresh it; if you are using an API key, confirm it starts with icog_ and has not been revoked at developers.cognitivx.io/keys.

403 Forbidden

You are authenticated but the action is not permitted. Here detail is an object whose error field tells you which gate you hit.

Email not verified (gates /api/chat, /api/senses, /api/introspect, /api/suggest and similar):

{
  "detail": {
    "error": "email_not_verified",
    "message": "Verify your email to use this feature"
  }
}

Tier too low:

{
  "detail": {
    "error": "tier_insufficient",
    "current_tier": "awakened",
    "required_tier": "conscious",
    "upgrade_url": "https://developers.cognitivx.io/billing"
  }
}

A paid-feature gate uses error: "feature_gate_denied" with feature, current_tier, recommended_tier, and upgrade_url. Admin-only and org-membership failures return a plain string detail (Admin access required, Not a member of this organization).

429 Too Many Requests

429 covers three distinct situations, distinguishable by the body. Read Rate limits for the full picture.

Auth rate limiter. A fixed limit of 5 requests per 60 seconds per client IP, applied only to the auth endpoints (/api/auth/signup, /signin, /forgot-password, /reset-password, /resend-verification). No Retry-After or X-RateLimit-* headers are sent.

{
  "detail": "Too many requests. Please try again later."
}

Tier quota exceeded. You hit a monthly message or recall cap for your tier. detail is an object:

{
  "detail": {
    "error": "quota_exceeded",
    "message": "Monthly recall quota reached",
    "quota": { "used": 1000, "limit": 1000, "remaining": 0 },
    "current_tier": "awakened",
    "recommended_tier": "conscious",
    "upgrade_url": "https://developers.cognitivx.io/billing"
  }
}

Budget or credit depletion. Memory routes (/api/recall, /api/remember, /api/talk) surface a quota error as a structured detail object when your credits run out. Top up or upgrade.

Retry guidance

There is no Idempotency-Key header. Because most write operations are not idempotent, only retry writes when you received a 5xx (the server may not have processed the request) or a network error, and keep retries bounded.

Catching errors in TypeScript

The @cognitivx/sdk throws an ApiError for any non-2xx response. It exposes three properties:

import { configureApiClient, memory, ApiError } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

try {
  const result = await memory.recall({ query: 'what did we decide about billing', limit: 5 });
  console.log(result.memories);
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`iCog returned ${err.status}: ${err.message}`);
    console.error('body:', err.body);
  } else {
    throw err; // network or unexpected error
  }
}

import { configureApiClient, memory, ApiError } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

try {
  await memory.remember({ content: 'Parsa prefers limit/offset pagination', memory_type: 'semantic' });
} catch (err) {
  if (!(err instanceof ApiError)) throw err;

  switch (err.status) {
    case 401:
      // Credential is bad or expired. Refresh or replace the key, then retry.
      console.error('Auth failed:', err.message);
      break;

    case 403: {
      // detail is a structured object; read it from body.
      const detail = (err.body as { detail?: { error?: string; upgrade_url?: string } }).detail;
      console.error('Forbidden:', detail?.error, detail?.upgrade_url);
      break;
    }

    case 422: {
      // detail is an array of field errors.
      const fields = (err.body as { detail?: { loc: string[]; msg: string }[] }).detail ?? [];
      for (const f of fields) console.error(`${f.loc.join('.')}: ${f.msg}`);
      break;
    }

    case 429:
      // Quota or rate limit. Back off; do not hammer the endpoint.
      console.error('Rate limited or over quota:', err.body);
      break;

    default:
      if (err.status >= 500) {
        // Transient. Safe to retry with backoff.
        console.error('Server error, retrying later:', err.status);
      } else {
        console.error('Request error:', err.status, err.message);
      }
  }
}

Related