Error Codes

All Rekall API errors follow a consistent format with HTTP status codes and Rekall-specific error codes. Use this reference to diagnose and resolve issues.

Error Format

Every error response includes a machine-readable error code, a human-readable message, the HTTP status, and a unique request ID for debugging.

Error Response Format

{
  "error": {
    "code": "INVALID_MEMORY_TYPE",
    "message": "The memory type 'spatial' is not supported.",
    "status": 400,
    "details": {
      "provided": "spatial",
      "allowed": ["episodic", "semantic", "procedural", "long-term", "short-term", "execution", "preferences"]
    },
    "request_id": "req_abc123def456"
  }
}

HTTP Status Codes

Status	Title	Description	Resolution
400	Bad Request	The request body is malformed, missing required fields, or contains invalid values.	Check the request payload against the API documentation. Validate all required fields are present and correctly typed.
401	Unauthorized	The request lacks valid authentication credentials. The API key is missing, expired, or invalid.	Verify your API key is correctly set in the Authorization header as a Bearer token. Check the key has not been revoked.
403	Forbidden	The authenticated user does not have permission to perform the requested action. Insufficient scopes.	Review the scopes assigned to your API key in the dashboard. Ensure the key has the required scope for the endpoint.
404	Not Found	The requested resource does not exist. The ID may be incorrect or the resource may have been deleted.	Verify the resource ID is correct. Check if the resource was recently deleted. Use listing endpoints to find valid IDs.
409	Conflict	The request conflicts with the current state of the resource. Common with duplicate entities or relationships.	Check if the resource already exists. For relationships, verify the source and target entities are different.
422	Unprocessable Entity	The request is well-formed but contains semantic errors. Often related to invalid memory content or metadata.	Review the specific error code in the response. Check that values are within allowed ranges and formats.
429	Too Many Requests	Rate limit exceeded. The request was throttled based on your plan tier limits.	Implement exponential backoff. Check the Retry-After header for when you can retry. Consider upgrading your plan.
500	Internal Server Error	An unexpected error occurred on the server. This is not caused by your request.	Retry the request after a short delay. If the error persists, check the Rekall status page or contact support.

Rekall Error Codes

These application-specific error codes provide more detail about what went wrong. They are returned in the error.code field of the response.

Code	HTTP	Description	Resolution
`INVALID_MEMORY_TYPE`	400	The specified memory type is not one of the 7 supported types.	Use one of: episodic, semantic, procedural, long-term, short-term, execution, preferences.
`SCOPE_INSUFFICIENT`	403	Your API key does not have the required scope for this endpoint.	Add the missing scope to your API key in the dashboard. The required scope is included in the error details.
`RATE_LIMIT_EXCEEDED`	429	You have exceeded the rate limit for your plan tier.	Implement exponential backoff. Check X-RateLimit-Reset header. Upgrade your plan for higher limits.
`ENTITY_NOT_FOUND`	404	The referenced entity does not exist in the knowledge graph.	Verify the entity ID. The entity may have been deleted or may belong to a different context.
`RELATIONSHIP_CONFLICT`	409	A relationship of this type already exists between the specified entities.	Update the existing relationship instead of creating a new one, or use a different relationship type.
`MEMORY_CONTENT_TOO_LARGE`	422	The memory content exceeds the maximum allowed size (100KB for text, 10MB for embeddings).	Reduce the content size. Split large content into multiple memories if needed.
`EMBEDDING_GENERATION_FAILED`	422	The system failed to generate a vector embedding for the provided content.	Ensure the content is valid text. Empty strings and binary data cannot be embedded.
`HIVE_MEMBER_LIMIT`	422	The hive has reached the maximum number of members allowed by your plan.	Remove existing members or upgrade your plan to increase the member limit.
`WORKFLOW_STEP_FAILED`	422	A workflow step failed during execution. The run has been paused.	Check the step error details in the workflow run response. Fix the step condition and retry.
`AGENT_ALREADY_TERMINATED`	409	The agent has already been terminated and cannot accept further operations.	Spawn a new agent instance from the same husk if you need to continue.
`SANDBOX_PRODUCTION_MISMATCH`	403	A sandbox key (rk_test_) was used to access production resources, or vice versa.	Use the correct key type for the environment. Sandbox keys only access sandbox data.
`CONTEXT_NOT_ACCESSIBLE`	403	The memory context (agent, user, or hive) is not accessible with the current credentials.	Ensure your API key has access to the specified context. Hive contexts require hive membership.

Handling Errors

refresh

Retryable errors

Errors with status 429 and 500 are generally retryable. Use exponential backoff starting at 1 second with a maximum of 5 retries.

timer

Rate limit headers

Every response includes rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Use these proactively to avoid hitting limits.

bug_report

Request ID for support

Include the request_id when contacting support. It is also returned in the X-Request-Id response header.

SDK error handling

The official SDKs automatically handle retryable errors with configurable backoff. Set maxRetries in the client constructor to control retry behavior.