Error Reference

NeuralSnap uses standard HTTP status codes and returns consistent error objects. Every error response includes a machine-readable code, a human-readable message, and optional details with field-level information.

Error Response Shape

typescript

interface ErrorResponse {
  error: {
    code: string;       // Machine-readable error code (e.g. "BAD_REQUEST")
    message: string;    // Human-readable description
    details?: {         // Optional field-level details
      field?: string;
      reason?: string;
      retry_after?: number;
      [key: string]: unknown;
    };
  };
}

Handling Errors

javascript

const res = await fetch("https://api.neuralsnap.ai/v1/snapshots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ns_test_abc123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Test" }), // Missing required 'core' field
});

if (!res.ok) {
  const { error } = await res.json();
  
  switch (res.status) {
    case 400:
      console.error(`Validation error: ${error.message}`);
      break;
    case 401:
      console.error("Re-authenticate and try again");
      break;
    case 429:
      const retryAfter = error.details?.retry_after || 30;
      console.log(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      // retry the request
      break;
    default:
      console.error(`Unexpected error (${res.status}): ${error.message}`);
  }
}

Error Codes

400Bad Request

The request body is malformed or missing required fields.

Common Causes

Missing a required field (e.g. name, core for snapshots)
Invalid JSON in request body
Invalid enum value (e.g. type must be Belief, Model, Rule, Conviction, or Principle)
Value out of range (e.g. confidence must be 0–1)

Example Response

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing required field: core",
    "details": {
      "field": "core",
      "reason": "required"
    }
  }
}

401Unauthorized

Authentication failed — missing, expired, or invalid credentials.

Common Causes

No Authorization header provided
API key is invalid or revoked
Session token has expired (re-authenticate)
Using a session token on a /v1/ endpoint (use API key instead)

Example Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

403Forbidden

You authenticated successfully but don't have permission for this action.

Common Causes

Trying to access another user's brain or snapshots
API key doesn't have the required scope
Account is suspended or on a restricted plan

Example Response

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have access to this brain"
  }
}

404Not Found

The requested resource doesn't exist.

Common Causes

Snapshot, memory, edge, or brain ID is wrong
Resource was previously deleted
Typo in the endpoint path

Example Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Snapshot not found: snap_invalid123"
  }
}

409Conflict

The request conflicts with existing data.

Common Causes

Duplicate edge — an edge of the same type already exists between two snapshots
Attempting to create a resource that already exists

Example Response

{
  "error": {
    "code": "CONFLICT",
    "message": "An edge of type 'supports' already exists between these snapshots"
  }
}

422Unprocessable Entity

The request is well-formed but semantically invalid.

Common Causes

Snapshots in an edge belong to different brains
Text too short for crystallization (minimum 20 characters)
Unsupported source_type for knowledge ingestion

Example Response

{
  "error": {
    "code": "UNPROCESSABLE",
    "message": "Source and target snapshots must belong to the same brain"
  }
}

429Too Many Requests

You've exceeded the rate limit. Back off and retry.

Common Causes

Too many requests in a short window
Burst limit exceeded (see Rate Limiting docs)

Example Response

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "details": {
      "retry_after": 30,
      "limit": 100,
      "window": "60s"
    }
  }
}

500Internal Server Error

Something went wrong on our side. If this persists, contact support.

Common Causes

Unexpected server error
Temporary infrastructure issue
AI model timeout during crystallization

Example Response

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again."
  }
}

Retry strategy

For 429 and 500 errors, use exponential backoff: wait 1s, then 2s, then 4s, up to a maximum of 30s. Always check the retry_after field in 429 responses — it tells you exactly how long to wait.

Profile & Usage

Rate Limiting