Skip to main content
Splendor uses conventional HTTP status codes and returns a consistent error envelope. The 2xx range means success, 4xx means the request was rejected, and 5xx means a server-side or upstream problem.

​
The error envelope

Every error response has a detail field. For most errors it is a human-readable string; for validation and capacity errors it is a structured object with a stable code and a message. 
{ "detail": "Dataset not found" }
Request validation errors (422) use the standard schema-validation shape, with a detail array describing each invalid field.

​
Status codes

StatusMeaning
400The request is invalid.
401The bearer token is missing, malformed, or expired.
403The token lacks access to the tenant, or the role the operation requires.
404The resource does not exist.
409The request conflicts with the current state of the resource.
410A search handle, cursor, or view has expired. Re-run the search or re-create the view.
422The request failed schema validation.
502An upstream provider request failed.
503A required backend is temporarily unavailable or at capacity.

​
Machine-readable codes

Structured errors carry a code you can branch on. The most common:
CodeStatusMeaning
semantic_query_text_required400Semantic search needs non-empty text.
semantic_query_dataset_required400Semantic search needs at least one dataset.
semantic_query_unsupported400The request shape is not supported for semantic search.
semantic_vector_backend_unconfigured503Semantic search is not configured for this tenant.
semantic_search_capacity_exhausted503Semantic search is temporarily at capacity.
semantic_provider_capacity_exhausted503The embedding/reranking provider is at capacity.
cold_search_capacity_exhausted503Cold-tier search is temporarily at capacity.
semantic_provider_request_failed502The embedding/reranking provider request failed.
semantic_vector_backend_request_failed502The vector backend request failed.

​
Retrying

Capacity errors (503) are transient. They include a Retry-After header indicating how long to wait before retrying. Back off and retry rather than failing the request outright.
Branch on the code for structured errors and on the HTTP status otherwise. Treat 5xx as retryable with backoff (honoring Retry-After on 503); treat 4xx as something to fix in the request.