Errors

HTTP status codes and error body shapes returned by the Valori Cloud API.

Two layers can produce an error: Cloud-side authentication (before your request reaches your project's node) and the node itself (once your request is running against your data). They use two different, both intentionally simple, body shapes.

Authentication errors (Cloud layer)

{ "error": "invalid, revoked, expired, or missing API key" }

Status	Meaning
`401`	The `Authorization` header is missing, malformed, or the key is invalid, revoked, or expired.
`409`	The key is valid but the project isn't ready to serve requests yet.
`429`	Too many requests for this key's project. A `Retry-After` header gives the wait in seconds — see Rate limits.

Operation errors (node layer)

Once a request is authenticated, the node's own errors carry a stable, machine-readable code alongside the human-readable error message — branch on code, not the message text:

{ "error": "dimension mismatch: expected 768, got 8", "code": "dimension_mismatch" }

Status	`code`	Meaning
`400`	`validation_error`, `dimension_mismatch`, `invalid_metric`, `invalid_index`	The request body failed validation.
`404`	`not_found`, `collection_not_found`, `record_not_found`	The target collection or record doesn't exist.
`409`	`conflict`	A collection already exists with a conflicting configuration.
`500`	`internal_error`	Commit or audit-chain failure. Safe to retry.
`503`	`unavailable`	The node is temporarily unable to serve requests.
`507`	`capacity_exceeded`	The project's record capacity is exhausted.

Recommended handling

Treat 401 as non-retryable — the key itself needs attention.
429 and 503 are retryable; respect Retry-After when present.
400/404/409 indicate the request itself needs to change, not a retry.