Error Handling

The Torvus Security API uses conventional HTTP status codes and returns detailed error information in JSON format.

---

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "vault_not_found",
    "message": "The requested vault could not be found",
    "details": {
      "vault_id": "vault_abc123xyz"
    },
    "request_id": "req_xyz789abc",
    "timestamp": "2025-10-08T14:00:00Z"
  }
}

---

HTTP Status Codes

Status Code	Meaning	When It Occurs
200	OK	Successful GET/PATCH request
201	Created	Successful POST (resource created)
204	No Content	Successful DELETE
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Temporary outage

---

Common Error Codes

Authentication Errors (401)

Error Code	Description	Solution
invalid_api_key	API key is invalid or expired	Check API key in dashboard
api_key_missing	Authorization header missing	Include Authorization: Bearer KEY
api_key_revoked	API key has been revoked	Generate new API key

Permission Errors (403)

Error Code	Description	Solution
insufficient_permissions	You lack permission for this action	Check your role/permissions
vault_access_denied	No access to this vault	Verify vault ownership
plan_limit_exceeded	Feature not available on your plan	Upgrade plan

Resource Errors (404)

Error Code	Description	Solution
vault_not_found	Vault doesn't exist	Check vault ID
document_not_found	Document doesn't exist	Check document ID
recipient_not_found	Recipient doesn't exist	Check recipient ID

Validation Errors (422)

Error Code	Description	Solution
invalid_vault_name	Vault name invalid	Use 1-100 characters
invalid_email	Email format invalid	Check email syntax
vault_already_released	Cannot modify released vault	Vault is immutable after release
missing_required_field	Required field missing	Check API documentation

---

Error Handling Best Practices

1. Check Status Code First

const response = await fetch('/api/v1/vaults', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error.error.message);
}

2. Handle Specific Error Codes

const error = await response.json();

switch (error.error.code) {
  case 'vault_not_found':
    // Handle missing vault
    break;
  case 'rate_limit_exceeded':
    // Implement retry with backoff
    break;
  case 'invalid_api_key':
    // Prompt for new API key
    break;
  default:
    // Generic error handling
}

3. Log Request IDs

Always log request_id from errors for support:

console.error(`Request ${error.error.request_id} failed:`, error.error.message);

4. Implement Retry Logic

async function retryableRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return response;
      }

      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(await response.text());
      }

      // Retry server errors (5xx)
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

---

Complete Error Code Reference

See individual endpoint documentation for endpoint-specific errors:

• Vaults API Errors
• Documents API Errors
• Recipients API Errors

---

Last Updated: October 8, 2025