Error Handling

The Rekall API uses conventional HTTP status codes and returns structured error objects to help you identify and resolve issues quickly.

Error Response Format

All error responses follow a consistent structure with an error object containing a machine-readable code, a human-readable message, and optional details about the error.

Error Response Structure

{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid fields.",
    "details": {
      "field": "type",
      "reason": "Must be one of: episodic, semantic, procedural, long_term, short_term, execution, preferences"
    }
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (e.g., `validation_error`)
`message`	string	Human-readable description of the error
`details`	object \| null	Additional context about the error (field-level validation errors, constraints, etc.)

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource was created successfully
`204`	No Content	Request succeeded with no response body (e.g., delete)
`400`	Bad Request	The request body is malformed or missing required fields
`401`	Unauthorized	Missing or invalid authentication credentials
`403`	Forbidden	Valid credentials but insufficient permissions or scopes
`404`	Not Found	The requested resource does not exist
`409`	Conflict	The request conflicts with the current state of the resource
`422`	Unprocessable Entity	The request was well-formed but contains semantic errors
`429`	Too Many Requests	Rate limit exceeded. Check Retry-After header
`500`	Internal Server Error	An unexpected error occurred on the server

Error Code Reference

The error.code field provides a machine-readable identifier for the error. Use these codes in your error handling logic.

Code	HTTP Status	Description
`bad_request`	400	Malformed JSON or invalid request structure
`authentication_required`	401	No authentication credentials provided
`invalid_token`	401	Token is expired, revoked, or malformed
`insufficient_permissions`	403	Token lacks the required scopes for this action
`resource_not_found`	404	The specified resource ID does not exist
`conflict`	409	Resource already exists or state conflict
`validation_error`	422	Request body failed validation (see details for fields)
`rate_limit_exceeded`	429	Too many requests in the current window
`internal_error`	500	Unexpected server error. Contact support if persistent

Handling Errors

Here are examples of robust error handling patterns for common scenarios.

Error Handling Examples

async function createMemory(content: string) {
  const response = await fetch('https://api.rekall.ai/v1/memories', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.REKALL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ type: 'episodic', content }),
  });

  if (!response.ok) {
    const { error } = await response.json();

    switch (error.code) {
      case 'authentication_required':
      case 'invalid_token':
        throw new Error('Invalid API key. Check your credentials.');

      case 'insufficient_permissions':
        throw new Error(`Missing scope: ${error.details?.required_scope}`);

      case 'validation_error':
        throw new Error(`Validation failed: ${error.message}`);

      case 'rate_limit_exceeded':
        const retryAfter = response.headers.get('Retry-After');
        throw new Error(`Rate limited. Retry after ${retryAfter}s`);

      case 'internal_error':
        throw new Error('Server error. Please retry or contact support.');

      default:
        throw new Error(`API error: ${error.message}`);
    }
  }

  const { data } = await response.json();
  return data;
}

Validation Errors

When the API returns a 422 status with a validation_error code, the details field contains specific information about which fields failed validation.

Validation Error Example

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "type",
          "message": "Required field is missing"
        },
        {
          "field": "content",
          "message": "Must be between 1 and 50000 characters"
        },
        {
          "field": "metadata.tags",
          "message": "Must be an array of strings"
        }
      ]
    }
  }
}

Debugging Tips

Check the request ID

Every API response includes an X-Request-Id header. Include this ID when contacting support for faster debugging.

Use sandbox keys for testing

Test error handling logic using rk_sandbox_ keys. The sandbox environment simulates all error types.

Log error details

Always log the full error response body, including the details field. This context is invaluable when debugging production issues.

SDK error classes

The official SDKs provide typed error classes for each error code. For example, the TypeScript SDK throws RekallAuthError, RekallValidationError, and RekallRateLimitError for easy pattern matching.