Verified by the sovseal team
Errors
Error response format and codes used by the sovseal edge function.
When a request fails, the edge function returns a standard JSON error envelope with an appropriate HTTP status code.
Error Response Envelope
Unlike the legacy success/error wrappers, the production edge endpoint returns a flat error object containing the error code:
{
"error": "sequence_gap"
}Error Code Reference
The following table documents the codes returned by the API, grouped by their HTTP status codes:
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 Bad Request | invalid_json | The request body could not be parsed as valid JSON. |
missing_field:<field> | A required field (e.g. agent_id, ciphertext_b64) is missing. | |
bad_policy_hash | The policy_hash field is not a valid 64-hex string. | |
bad_payload_hash | The client_payload_hash field is not a valid 64-hex string. | |
bad_sequence | The sequence_number is invalid or negative. | |
genesis_violation | The sequence number is 0 but parent_snapshot is not null. | |
missing_parent_snapshot | The sequence number is > 0 but no parent snapshot ID was provided. | |
byte_size_mismatch | Decoded base64 ciphertext length does not match byte_size. | |
missing_since_param | The since query parameter is missing on a replay request. | |
| 401 Unauthorized | missing_or_invalid_bearer_token | The Authorization header is empty or malformed. |
session_jwt_required | The endpoint requires a user login session JWT, not an API key. | |
invalid_session | The Supabase user session token is expired or invalid. | |
invalid_api_key | The hashed sov_live_ key was not found in the database. | |
api_key_revoked | The API key was soft-deleted/revoked. | |
owner_not_found | The key owner's user record was not found in the platform. | |
| 402 Payment Required | insufficient_credits | The key owner has run out of state sync credits. |
| 403 Forbidden | not_a_team_member | The authenticated user is not a member of the requested ZK team. |
forbidden_role | The member's role (e.g. read) lacks permissions for the action. | |
telemetry_disabled | The user's persisted dashboard settings have telemetry opted off. | |
no_grant | The member has not accepted the team invite or holds no wrapped key grant. | |
| 404 Not Found | no_snapshots_for_agent | The agent has no confirmed snapshots to restore. |
snapshot_not_found | No snapshot exists for the requested sequence number. | |
route_not_found | The request URL does not map to any active handler. | |
| 409 Conflict | sequence_conflict | A snapshot already exists at this sequence number with a different hash. |
sequence_gap | The requested snapshot sequence number is not exactly latest + 1. | |
split_brain_detected | A duplicate sequence insertion has different data hashes (replication conflict). | |
| 413 Payload Too Large | ciphertext_too_large | Decrypted ciphertext exceeds MAX_PAYLOAD_BYTES (10 MB). |
chunk_too_large | Decoded replication chunk exceeds MAX_CHUNK_BYTES (256 KB). | |
| 503 Service Unavailable | storage_unavailable | The storage backend (Supabase Storage/Arweave) was temporarily unreachable. |