Error Codes

Complete reference of 30 error codes across 9 categories returned by the RAG Service.

Error response formatjson

{
  "error": {
    "code": "RAG_1100",
    "message": "Search query is empty or exceeds maximum length",
    "http": 400
  }
}

IngestionRAG_1000-1099

Code	HTTP	Name	Description	Resolution
`RAG_1000`	400	`INVALID_DOCUMENT`	Document content is empty, too large, or in an unsupported format	Check document size limits (max 50MB) and supported formats (PDF, DOCX, TXT, MD, HTML)
`RAG_1001`	400	`INVALID_SOURCE_TYPE`	Unrecognized ingestion source type	Use valid source types: manual, confluence, notion, google-drive, sharepoint, url
`RAG_1002`	409	`DOCUMENT_ALREADY_EXISTS`	Document with this source ID already exists in the namespace	Use PUT to update existing documents or use a different source ID
`RAG_1003`	502	`CHUNKING_FAILED`	Document chunking pipeline failed	Check document encoding and format; retry with different chunking strategy
`RAG_1004`	502	`EMBEDDING_GENERATION_FAILED`	Embedding model failed to generate vectors	Retry; embedding provider may be temporarily unavailable

Code	HTTP	Name	Description	Resolution
`RAG_1100`	400	`INVALID_QUERY`	Search query is empty or exceeds maximum length	Provide a non-empty query (max 10,000 characters)
`RAG_1101`	400	`INVALID_SEARCH_TYPE`	Unrecognized search type	Use valid search types: semantic, keyword, hybrid
`RAG_1102`	400	`INVALID_TOP_K`	topK value out of range	Provide topK between 1 and 100
`RAG_1103`	502	`VECTOR_STORE_ERROR`	Vector database returned an error	Retry; OpenSearch/vector store may be scaling
`RAG_1104`	404	`NAMESPACE_NOT_FOUND`	The specified namespace does not exist	Create the namespace first or check the namespace ID

Code	HTTP	Name	Description	Resolution
`RAG_1200`	400	`INVALID_GOLDEN_SET`	Golden set format is invalid or contains insufficient examples	Provide at least 10 query-answer pairs with relevance scores
`RAG_1201`	400	`INVALID_EVALUATION_METRIC`	Unrecognized evaluation metric	Use valid metrics: ndcg, mrr, map, precision, recall, f1
`RAG_1202`	409	`TRAINING_IN_PROGRESS`	A training job is already running for this namespace	Wait for the current training job to complete or cancel it
`RAG_1203`	502	`TRAINING_FAILED`	Training pipeline encountered an error	Check training logs and retry with adjusted parameters

Code	HTTP	Name	Description	Resolution
`RAG_1300`	400	`INVALID_EMBEDDING_MODEL`	Requested embedding model is not configured	Use GET /config/embedding-models to list available models
`RAG_1301`	400	`DIMENSION_MISMATCH`	Embedding dimensions do not match the index configuration	Ensure the embedding model matches the namespace index dimensions (default: 1024)
`RAG_1302`	502	`MODEL_PROVIDER_ERROR`	Embedding model provider returned an error	Retry; provider failover may activate automatically

Code	HTTP	Name	Description	Resolution
`RAG_1400`	401	`UNAUTHORIZED`	Authentication required	Provide a valid JWT token in Authorization header
`RAG_1401`	403	`FORBIDDEN`	Insufficient permissions for this operation	Request required role from admin
`RAG_1402`	401	`INVALID_TOKEN`	Invalid or expired authentication token	Obtain a fresh JWT token via auth-svc
`RAG_1403`	403	`TIER_INSUFFICIENT`	Current subscription tier does not support this RAG feature	Training features require Pro tier; Custom GPT sync requires Enterprise

Code	HTTP	Name	Description	Resolution
`RAG_1500`	400	`VALIDATION_FAILED`	Request validation failed	Check request body against API docs
`RAG_1501`	400	`MISSING_REQUIRED_FIELD`	Required field is missing	Add the required field to the request body
`RAG_1502`	400	`INVALID_UUID`	Provided ID is not a valid UUID	Use standard UUID v4 format

Code	HTTP	Name	Description	Resolution
`RAG_1600`	400	`INVALID_DATE_RANGE`	Date range is invalid or exceeds maximum span	Ensure startDate < endDate and span does not exceed 90 days
`RAG_1601`	404	`DASHBOARD_NOT_FOUND`	Analytics dashboard not found for this tenant	Ensure documents have been ingested before querying analytics

Code	HTTP	Name	Description	Resolution
`RAG_1900`	500	`DATABASE_ERROR`	Database operation failed	Retry; Aurora Serverless may be scaling up
`RAG_1901`	500	`TRANSACTION_FAILED`	Database transaction failed	Retry the operation

Code	HTTP	Name	Description	Resolution
`RAG_2000`	500	`INTERNAL_SERVER_ERROR`	Internal server error	Retry; if persistent, contact support with request_id
`RAG_2001`	503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry with exponential backoff