REST API: Errors & Limits Error handling, rate limits, and resource quotas in the Trix REST API.
Updated Oct 6, 2026
The Trix API uses conventional HTTP response codes to indicate the success or
failure of requests. Codes in the 2xx range indicate success, 4xx indicate
client errors, and 5xx indicate server errors.
Success Codes Code Description 200 OKRequest succeeded 201 CreatedResource created successfully 204 No ContentSuccessful deletion, no response body
Client Error Codes Code Description 400 Bad RequestInvalid request parameters or body 401 UnauthorizedMissing or invalid authentication 403 ForbiddenValid auth but insufficient permissions 404 Not FoundResource doesn't exist 409 ConflictResource conflict (e.g., duplicate) 422 Unprocessable EntityValid syntax but semantic errors 429 Too Many RequestsRate limit exceeded
Server Error Codes Code Description 500 Internal Server ErrorUnexpected server error 502 Bad GatewayUpstream service unavailable 503 Service UnavailableTemporary overload or maintenance 504 Gateway TimeoutRequest took too long
Authentication Errors Code HTTP Description missing_auth401 No Authorization header provided invalid_api_key401 API key doesn't exist or was revoked expired_token401 JWT token has expired insufficient_permissions403 Key lacks required permissions space_access_denied403 Key not authorized for this space
Validation Errors Code HTTP Description invalid_request400 Malformed JSON or invalid parameters missing_field400 Required field not provided invalid_field400 Field value failed validation content_too_large422 Memory content exceeds size limit invalid_embedding422 Custom embedding has wrong dimensions
Resource Errors Code HTTP Description not_found404 Resource doesn't exist duplicate_memory409 Memory with same content exists relationship_exists409 Relationship already exists space_not_empty409 Cannot delete space with memories
Rate Limit Errors Code HTTP Description rate_limit_exceeded429 Too many requests quota_exceeded429 Monthly quota exhausted concurrent_limit429 Too many concurrent requests
Rate limits protect the API from abuse and ensure fair usage. Limits are
applied per API key and vary by plan.
Default Limits Plan Requests/min Requests/day Concurrent Free 60 10,000 5 Pro 300 100,000 20 Max 1,000 500,000 50 Enterprise Unlimited Unlimited Unlimited
Rate Limit Headers Every response includes rate limit information:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 2024-01-15T10:31:00Z
Retry-After: 45 Header Description X-RateLimit-LimitMaximum requests per window X-RateLimit-RemainingRequests remaining in current window X-RateLimit-ResetISO 8601 datetime when window resets Retry-AfterSeconds until retry is allowed (only on 429 responses)
Handling Rate Limits async function fetchWithRetry(
url: string,
options: RequestInit,
maxRetries = 3
): Promise<Response> {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const resetAfter = parseInt(
response.headers.get('Retry-After') || '30'
);
console.log(`Rate limited. Waiting ${resetAfter}s...`);
await new Promise(r => setTimeout(r, resetAfter * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}
// Usage
const response = await fetchWithRetry(
'https://api.trixdb.com/v1/memories',
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
); In addition to rate limits, there are limits on resource sizes and counts:
Memory Limits Resource Limit Content size 1 MB per memory Tags per memory 100 Tag length 255 characters Metadata size 16 KB Bulk create batch 100 memories
Search Limits Resource Limit Results per page 100 Max offset 10,000 Query length 1,000 characters Filters per query 20
Graph Limits Resource Limit Traversal depth 5 hops Nodes per traversal 500 Relationships per memory 1,000 Context size 100 memories
Account Limits Resource Free Pro Max Enterprise Memories 1,000 100,000 500,000 Unlimited Spaces 3 Unlimited Unlimited Unlimited API Keys 3 10 50 Unlimited Webhooks 1 10 50 Unlimited
Implement Exponential Backoff async function fetchWithBackoff<T>(
fn: () => Promise<T>,
maxRetries = 5,
baseDelay = 1000
): Promise<T> {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error: unknown) {
const status = (error as { response?: { status?: number } }).response?.status;
// Don't retry client errors (except rate limits)
if (status >= 400 && status < 500 && status !== 429) {
throw error;
}
if (i === maxRetries - 1) throw error;
// Exponential backoff with jitter
const delay = baseDelay * Math.pow(2, i) + Math.random() * 1000;
await new Promise(r => setTimeout(r, delay));
}
}
throw new Error('Unreachable');
} Handle Specific Errors async function handleApiError(error: ApiError) {
switch (error.code) {
case 'rate_limit_exceeded':
// Wait and retry
await sleep(error.details?.reset_after || 60);
return retry();
case 'duplicate_memory':
// Return existing memory
return getMemory(error.details?.existing_id);
case 'content_too_large':
// Split content and retry
return createChunkedMemories(content);
case 'invalid_api_key':
// Refresh credentials
await refreshApiKey();
return retry();
default:
// Log and rethrow
console.error('Unhandled API error:', error);
throw error;
}
} Include the request_id from error responses when contacting support. This helps us quickly locate and diagnose issues.
Health Check Check API status without authentication:
curl -X GET "https://api.trixdb.com/v1/health"
# Response
{
"status": "ok",
"uptime": 86400,
"version": "1.2.3",
"timestamp": "2024-01-15T10:30:00Z"
}