Error Handling

ExoVault uses standard HTTP status codes and consistent JSON error responses. This page covers all error types, their formats, and recommended retry strategies.

Error Response Format#

Authentication & Authorization Errors#

{
  "error": "Missing or invalid agent key"
}

Status: 401

Validation Errors#

{
  "error": "Validation failed",
  "fields": {
    "content": "String must contain at least 1 character(s)",
    "importance": "Number must be less than or equal to 5"
  }
}

Status: 400

The fields property maps field names to their specific validation errors. This only appears on 400 validation responses.

Server Errors#

{
  "error": "Internal server error"
}

Status: 500

Error Types#

AuthError (401, 403)#

Thrown by the authentication and authorization middleware.

ValidationError (400)#

Thrown when the request body fails Zod schema validation. The fields property provides per-field details.

Common validation failures:

Quota Errors (429)#

{
  "error": "QUOTA_EXCEEDED: Memory monthly quota exceeded"
}

Status: 429

Thrown when the user's monthly memory usage quota is exceeded. Applies to both write-memory and search-memories operations.

Rate Limit Errors (429)#

Certain routes (e.g., send-message) have per-user rate limits:

{
  "error": "Too many requests",
  "retryAfter": 60
}

Status: 429

Error Codes Summary#

These codes appear as prefixes in the error message string (e.g., "SCOPE_DENIED: This key does not have...") to enable programmatic detection.

Retry Strategies#

Retryable Errors#

Non-Retryable Errors#

Recommended Retry Pattern#

async function callWithRetry(
  fn: () => Promise<Response>,
  maxRetries = 3
): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fn();

    if (response.ok) return response;

    if (response.status === 429) {
      const body = await response.json();
      const waitMs = (body.retryAfter ?? 60) * 1000;
      await sleep(waitMs);
      continue;
    }

    if (response.status >= 500 && attempt < maxRetries) {
      const waitMs = Math.min(1000 * 2 ** attempt, 30000);
      const jitter = Math.random() * waitMs * 0.1;
      await sleep(waitMs + jitter);
      continue;
    }

    throw new Error(`API error: ${response.status}`);
  }
}

Idempotency#

Several write routes support idempotency via externalWriteId:

• write-memory
• create-task
• context-checkpoint (auto-generated from agentRunId)

When a request with the same externalWriteId is received, the server returns the existing resource instead of creating a duplicate:

{
  "memoryId": "existing-id",
  "idempotent": true
}

Status: 200 (not 201)

This makes it safe to retry write operations without risk of duplication.

Related Pages#

• API Overview -- Request/response format
• Authentication -- Auth errors and scopes
• Agent Routes -- Route-specific parameters
• Limits and Quotas -- Quota details