Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Complete reference for sovseal API error response envelope format and all error codes, grouped by HTTP status from 400 through 503.
error field — not the HTTP status alone — since multiple distinct conditions can share a status code. The error envelope format is consistent across all endpoints.
{
"error": "sequence_gap"
}
conflicts array:
{
"error": "split_brain_detected",
"conflicts": [
{
"sequence_number": 10,
"existing_block_hash": "f5a2b3c4...",
"attempted_block_hash": "e3b0c442..."
}
]
}
| Error Code | Description |
|---|---|
invalid_json | The request body could not be parsed as valid JSON. |
missing_field:<field> | A required field is absent. The field name is appended after the colon (e.g. missing_field:agent_id, missing_field:ciphertext_b64). |
bad_policy_hash | The policy_hash field is not a valid 64-character hex string. |
bad_payload_hash | The client_payload_hash field is not a valid 64-character hex string. |
bad_sequence | The sequence_number value is invalid (e.g. negative or non-integer). |
genesis_violation | sequence_number is 0 but parent_snapshot is not null. |
missing_parent_snapshot | sequence_number is greater than 0 but no parent_snapshot was provided. |
byte_size_mismatch | The decoded length of ciphertext_b64 does not match the submitted byte_size. |
missing_since_param | The since query parameter is required but was not included on a /replay request. |
| Error Code | Description |
|---|---|
missing_or_invalid_bearer_token | The Authorization header is absent or does not follow the Bearer <TOKEN> format. |
session_jwt_required | The endpoint requires a dashboard session JWT but received an agent API key (sov_live_ or sov_proj_). |
invalid_session | The session JWT (issued by WorkOS AuthKit) is expired or failed verification against the remote JWKS. |
invalid_api_key | The SHA-256 hash of the submitted sov_live_ key was not found in the database. |
api_key_revoked | The API key was previously revoked and is no longer valid for any operation. |
owner_not_found | The user account linked to this API key does not exist on the platform. |
| Error Code | Description |
|---|---|
insufficient_credits | The key owner’s per-write credit balance (credits_milli) is insufficient. This gate applies to sov_live_ keys only — sov_proj_ tokens are never debited. |
credits_milli defaults to 0 on every account and is not funded by subscribing to a paid plan through Polar — the current subscription webhook updates plan/quota fields but does not grant credits. If you are hitting this error on a paid key, that is very likely a billing-configuration issue on our end rather than something you can resolve by upgrading. Contact enterprise@sovseal.com if you see this.| Error Code | Description |
|---|---|
not_a_team_member | The authenticated user is not a member of the requested ZK team. |
forbidden_role | The member’s assigned role (e.g. read) does not permit this operation. |
telemetry_disabled | The user’s dashboard settings have telemetry opted out — the telemetry endpoint will not accept submissions. |
no_grant | The member has not accepted their team invite or does not hold a wrapped DEK grant for the requested team. |
| Error Code | Description |
|---|---|
no_snapshots_for_agent | The agent has no confirmed snapshots to restore (genesis snapshot has not been written yet). |
snapshot_not_found | No confirmed snapshot exists for the requested sequence number. |
route_not_found | The request path does not map to any active handler in the edge function. |
no_replication_entries | Returned by GET /head when the agent has not pushed any replication chunks yet. |
| Error Code | Description |
|---|---|
sequence_conflict | A snapshot already exists at this sequence number with a different payload hash. |
sequence_gap | The submitted sequence_number for a snapshot is not exactly latest + 1 — gaps in the sequence chain are not permitted. |
split_brain_detected | A duplicate sequence number insertion was attempted with a different block_hash, indicating two offline clients diverged on the same sequence slot. The response body includes a conflicts array. |
| Error Code | Description |
|---|---|
ciphertext_too_large | The decoded ciphertext_b64 for a snapshot upload exceeds 256 KB (262,144 bytes, MAX_PAYLOAD_BYTES). |
chunk_too_large | The decoded ciphertext_b64 for a replication chunk exceeds 256 KB (MAX_CHUNK_BYTES). |
| Error Code | Description |
|---|---|
storage_unavailable | The object storage backend (Supabase Storage) was unreachable during the upload. Any credits debited for the failed operation are automatically refunded. Retry with exponential backoff. |