Errors | Spectron

Spectron uses standard HTTP status codes and follows RFC 7807 Problem Details for all error responses.

Error response format

All errors return a JSON body with the following fields:

{
  "type": "https://spectron.dev/errors/context-not-found",
  "title": "Context not found",
  "status": 404,
  "detail": "No context with id 'acme-staging' exists on this server.",
  "instance": "/api/v1/contexts/acme-staging"
}

Field	Description
`type`	A URI identifying the error type. Stable across versions.
`title`	A short, human-readable summary of the problem type.
`status`	The HTTP status code.
`detail`	A human-readable explanation specific to this occurrence.
`instance`	The request path that produced the error.

HTTP status codes

400 Bad Request

The request body or query parameters are invalid. Common causes:

Malformed JSON body
Missing required fields
Invalid field values (e.g. unknown mode for knowledge query)
Scope floor violation (requesting a scope narrower than the key's floor)

{
  "type": "https://spectron.dev/errors/validation-error",
  "title": "Validation error",
  "status": 400,
  "detail": "Field 'mode' must be one of: vector, bm25, hybrid, hybrid_graph. Got: 'fuzzy'.",
  "instance": "/api/v1/acme-prod/query"
}

401 Unauthorized

No API-KEY header was provided, or the key is malformed.

{
  "type": "https://spectron.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing. Include 'API-KEY: <key>' in your request.",
  "instance": "/api/v1/acme-prod/sessions"
}

403 Forbidden

The API key is valid but does not have permission to perform this operation. Common causes:

Agent key attempting a management operation
Key's scope floor does not include the requested scope
Agent key attempting to persist a reflection (requires supervisor principal)

{
  "type": "https://spectron.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This operation requires a management key. The provided key has principal 'agent'.",
  "instance": "/api/v1/contexts"
}

404 Not Found

The requested resource does not exist.

{
  "type": "https://spectron.dev/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No document with id 'document:0197d8f2...' exists in context 'acme-prod'.",
  "instance": "/api/v1/acme-prod/documents/0197d8f2"
}

409 Conflict

A resource with the same identifier already exists (e.g. creating a Context with a duplicate ID).

{
  "type": "https://spectron.dev/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A context with id 'acme-prod' already exists.",
  "instance": "/api/v1/contexts/acme-prod"
}

413 Payload Too Large

The uploaded file exceeds the per-Context size limit.

{
  "type": "https://spectron.dev/errors/payload-too-large",
  "title": "Payload too large",
  "status": 413,
  "detail": "Uploaded file size (52.4 MB) exceeds the per-context limit (50 MB).",
  "instance": "/api/v1/acme-prod/documents"
}

422 Unprocessable Entity

The request is syntactically valid but semantically invalid.

{
  "type": "https://spectron.dev/errors/unprocessable",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "Cannot bind context to namespace 'spectron' – this namespace is reserved for internal use.",
  "instance": "/api/v1/contexts/test"
}

429 Too Many Requests

The Context has exceeded its token limit or rate limit.

{
  "type": "https://spectron.dev/errors/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Monthly token limit of 1,000,000 has been reached for context 'acme-prod'.",
  "instance": "/api/v1/acme-prod/sessions/sess_abc/turns",
  "retry_after": null
}

500 Internal Server Error

An unexpected error occurred server-side. The detail field contains a request ID for support escalation.

{
  "type": "https://spectron.dev/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Request ID: req_01HF3X...",
  "instance": "/api/v1/acme-prod/context"
}

503 Service Unavailable

The server is temporarily unable to handle requests – typically during a SurrealDB connection issue or startup.

SDK exceptions

Python SDK

Exception	HTTP status	When
`SpectronAuthError`	401	Missing or invalid API key
`SpectronForbiddenError`	403	Insufficient principal or scope violation
`SpectronNotFoundError`	404	Resource does not exist
`SpectronConflictError`	409	Duplicate resource on create
`SpectronRateLimitError`	429	Token or rate limit exceeded
`SpectronValidationError`	400, 422	Invalid request payload
`SpectronServerError`	500, 503	Server-side failure

from spectron.exceptions import SpectronNotFoundError, SpectronRateLimitError

try:
    doc = await client.knowledge.get("document:nonexistent")
except SpectronNotFoundError as e:
    print(f"Document not found: {e.detail}")
except SpectronRateLimitError as e:
    print(f"Rate limit exceeded. Retry after: {e.retry_after}")

JavaScript SDK

Error class	HTTP status	When
`SpectronAuthError`	401	Missing or invalid API key
`SpectronForbiddenError`	403	Insufficient principal or scope violation
`SpectronNotFoundError`	404	Resource does not exist
`SpectronConflictError`	409	Duplicate resource on create
`SpectronRateLimitError`	429	Token or rate limit exceeded
`SpectronValidationError`	400, 422	Invalid request payload
`SpectronServerError`	500, 503	Server-side failure

import { SpectronNotFoundError, SpectronRateLimitError } from "spectron";

try {
    const doc = await client.knowledge.get("document:nonexistent");
} catch (e) {
    if (e instanceof SpectronNotFoundError) {
        console.error("Document not found:", e.detail);
    } else if (e instanceof SpectronRateLimitError) {
        console.error("Rate limit exceeded");
    }
}

Ingestion pipeline errors

Documents that fail during async processing do not return HTTP errors – they set the document status to "failed" and populate the error field:

{
  "id": "document:0197d8f2...",
  "status": "failed",
  "error": "PDF extraction failed: file is encrypted and no password was provided.",
  "processing_started_at": "2026-05-12T14:22:11Z",
  "processing_completed_at": "2026-05-12T14:22:14Z"
}

Poll GET /api/v1/{context_id}/documents/{id} to check document status. See Uploading documents for retry guidance.