Skip to main content

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.
Common scenarios:
  • Missing required parameters (tenant_id, query, etc.)
  • Invalid parameter formats
  • Malformed JSON in request body
  • Mutually exclusive parameters both provided (e.g., both source_id and chunk_ids)

401 Unauthorized

Authentication required or invalid.
Common scenarios:
  • Missing Authorization: Bearer $HYDRA_DB_API_KEY header (or any Authorization header at all)
  • Invalid API key
  • Expired API key

403 Forbidden

Authenticated, but the request is not permitted.
Common scenarios:
  • API key lacks required scopes
  • Tenant access restrictions
  • Cross-organization access attempts

404 Not Found

Requested resource does not exist.
Common scenarios:
  • TENANT_NOT_FOUND – tenant ID does not exist
  • SOURCE_NOT_FOUND – source/document not found
  • MEMORY_NOT_FOUND – memory ID does not exist
  • FILE_NOT_FOUND – file ID does not exist

409 Conflict

Resource already exists or conflicts with existing data.
Common scenarios:
  • TENANT_ALREADY_EXISTS – attempting to create a tenant with an in-use ID

422 Unprocessable Entity

Request is well-formed, but contains semantic errors.
Common scenarios:
  • Embedding vector dimension doesn’t match tenant configuration
  • Invalid tenant_metadata_schema field type
  • MemoryItem content fields all empty (no text and no user_assistant_pairs)
  • File metadata array length doesn’t match files array length

429 Too Many Requests

Rate limit exceeded.
When it occurs: Currently documented on recall endpoints (/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.
How to handle: Retry with exponential backoff. If the error persists, contact support with the response payload.

503 Service Unavailable

Service temporarily unavailable, often during deployments or under high load.
How to handle: Retry with exponential backoff. Most 503s resolve within seconds.

Endpoint-specific error codes

These error codes are returned in the detail.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

  1. Header format: Authorization: Bearer $HYDRA_DB_API_KEY – exactly one space between Bearer and the key value
  2. Key validity: Verify in app.hydradb.com
  3. Key permissions: Confirm scopes match your operation

Tenant not found after creation

Tenant creation is asynchronous. Poll GET /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_metadata array length doesn’t match files array length on /ingestion/upload_knowledge
  • Sending app_knowledge as a JSON object instead of a JSON-encoded string in multipart form data
  • MemoryItem with no text and no user_assistant_pairs

Empty results from recall

Not an error, but a common confusion:
  • Content may still be in processing or graph_creation state. Check via POST /ingestion/verify_processing.
  • metadata_filters may be too restrictive. Try without filters first.
  • Wrong endpoint: use /recall/recall_preferences for memories, /recall/full_recall for knowledge.
  • Wrong sub-tenant: pass sub_tenant_id explicitly if you stored under a non-default sub-tenant.

Rate limiting

For high-throughput workloads:
  1. Use bulk endpoints when possible (e.g., delete by array of IDs rather than one at a time)
  2. Implement exponential backoff for 429 responses
  3. Cache recall results when query patterns repeat
  4. Contact [email protected] for current limits
  • API Reference – endpoint-specific error codes are listed in each reference page
  • Quickstart – first-time setup guide