Standard error response format
Every error response follows this structure:Always read
detail.message and detail.error_code for the actual error context. The HTTP status alone is not specific enough to handle errors well.HTTP status codes
400 Bad Request
Invalid input parameters or malformed requests.- Missing required parameters (
tenant_id,query, etc.) - Invalid parameter formats
- Malformed JSON in request body
- Mutually exclusive parameters both provided (e.g., both
source_idandchunk_ids)
401 Unauthorized
Authentication required or invalid.- Missing
Authorization: Bearer $HYDRA_DB_API_KEYheader (or anyAuthorizationheader at all) - Invalid API key
- Expired API key
403 Forbidden
Authenticated, but the request is not permitted.- API key lacks required scopes
- Tenant access restrictions
- Cross-organization access attempts
404 Not Found
Requested resource does not exist.TENANT_NOT_FOUND– tenant ID does not existSOURCE_NOT_FOUND– source/document not foundMEMORY_NOT_FOUND– memory ID does not existFILE_NOT_FOUND– file ID does not exist
409 Conflict
Resource already exists or conflicts with existing data.TENANT_ALREADY_EXISTS– attempting to create a tenant with an in-use ID
422 Unprocessable Entity
Request is well-formed, but contains semantic errors.- Embedding vector dimension doesn’t match tenant configuration
- Invalid
tenant_metadata_schemafield type MemoryItemcontent fields all empty (notextand nouser_assistant_pairs)- File metadata array length doesn’t match files array length
429 Too Many Requests
Rate limit exceeded./recall/full_recall, /recall/recall_preferences, /recall/boolean_recall). Other endpoints may also return 429 under sustained load.
How to handle:
Implement exponential backoff. See Retry pattern below.
For current rate limit values, contact [email protected].
500 Internal Server Error
Unexpected server-side failure.503 Service Unavailable
Service temporarily unavailable, often during deployments or under high load.Endpoint-specific error codes
These error codes are returned in thedetail.error_code field of error responses. The list is non-exhaustive; new codes may be added.
Tenants
Ingestion
Memories
Recall
Embeddings
Retry pattern
For transient errors (429, 500, 503), implement exponential backoff:
Error handling patterns
Catching specific errors
Inspecting partial successes
Some bulk endpoints (e.g.,POST /knowledge/delete_knowledge, POST /memories/add_memory) can return 200 OK with partial successes inside the response. Always inspect per-item results:
Troubleshooting common issues
Authentication failures
- Header format:
Authorization: Bearer $HYDRA_DB_API_KEY– exactly one space betweenBearerand the key value - Key validity: Verify in app.hydradb.com
- Key permissions: Confirm scopes match your operation
Tenant not found after creation
Tenant creation is asynchronous. PollGET /tenants/infra/status until infra.scheduler_status, infra.graph_status, and both elements of infra.vectorstore_status are true before ingesting. Allow up to 5 minutes (Enterprise plans take longer than Free/Ship).
422 Validation Error on ingestion
Common causes:file_metadataarray length doesn’t matchfilesarray length on/ingestion/upload_knowledge- Sending
app_knowledgeas a JSON object instead of a JSON-encoded string in multipart form data MemoryItemwith notextand nouser_assistant_pairs
Empty results from recall
Not an error, but a common confusion:- Content may still be in
processingorgraph_creationstate. Check viaPOST /ingestion/verify_processing. metadata_filtersmay be too restrictive. Try without filters first.- Wrong endpoint: use
/recall/recall_preferencesfor memories,/recall/full_recallfor knowledge. - Wrong sub-tenant: pass
sub_tenant_idexplicitly if you stored under a non-default sub-tenant.
Rate limiting
For high-throughput workloads:- Use bulk endpoints when possible (e.g., delete by array of IDs rather than one at a time)
- Implement exponential backoff for
429responses - Cache recall results when query patterns repeat
- Contact [email protected] for current limits
Related sections
- API Reference – endpoint-specific error codes are listed in each reference page
- Quickstart – first-time setup guide