Error Reference

Overview

MatsuDB uses a standardized error system based on RFC 9457 Problem Details for HTTP APIs. All errors returned by the API follow a consistent structure that includes error codes, categories, detailed messages, and retry information. Errors are designed to be actionable, providing clear guidance on what went wrong and how to resolve issues.

The error system supports both HTTP and gRPC protocols, with automatic mapping between error codes and protocol-specific status codes. Each error includes structured information that enables applications to handle errors programmatically while providing human-readable messages for debugging.

Error Structure

All errors follow the MatsuError structure, which includes:

Code: A specific error code identifying the error type
Category: A category grouping errors by domain for observability
Problem Details: RFC 9457 compliant problem details with type, title, status, detail, and instance
Service: The service that generated the error
Operation: The operation that failed
Logging Metadata: Whether the error should be logged and at what level

Problem Details

The ProblemDetails structure provides RFC 9457 compliant error information:

{
  "type": "https://api-docs.biolevatecloud.com/errors/invalid-argument",
  "title": "Invalid Argument",
  "status": 400,
  "detail": "The provided node_id is not a valid integer",
  "instance": "/v1/nodes/abc123",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-01T12:00:00Z",
  "extensions": {
    "field": "node_id",
    "expected_type": "integer"
  },
  "validation_errors": [
    {
      "field": "node_id",
      "code": "INVALID_FORMAT",
      "message": "node_id must be a valid integer",
      "rejected_value": "abc123",
      "constraint": "integer_format"
    }
  ],
  "retry_info": {
    "retryable": false,
    "retry_after_ms": 0,
    "max_retries": 0,
    "backoff_type": "none",
    "backoff_ms": 0
  }
}

Validation Errors

When validation fails, the error includes a validation_errors array with detailed information about each field that failed validation:

field: The field path that failed (e.g., "node_id" or "tags[0]")
code: A validation error code (e.g., "REQUIRED", "TOO_SHORT", "INVALID_FORMAT")
message: Human-readable error message
rejected_value: The value that failed validation (optional, for security reasons)
constraint: The constraint that was violated (e.g., "min_length: 1")

Retry Information

For transient errors, the retry_info field provides guidance on whether and how to retry:

retryable: Whether the error is retryable
retry_after_ms: Recommended retry delay in milliseconds
max_retries: Maximum number of retries recommended
backoff_type: Backoff strategy ("linear" or "exponential")
backoff_ms: Base backoff duration in milliseconds

Error Codes

Client Errors (4xx)

`ERROR_CODE_INVALID_ARGUMENT` (1) - Invalid Argument

HTTP Status: 400 Bad Request
gRPC Code: InvalidArgument
Category: ERROR_CATEGORY_VALIDATION
Logging: Not logged (debug level)
Slug: invalid-argument

Indicates that a request argument is invalid or malformed. This error occurs when required parameters are missing, have incorrect types, or violate basic format requirements.

Common Causes:

Missing required parameters
Invalid parameter types
Malformed identifiers
Invalid enum values

Example:

{
  "code": "ERROR_CODE_INVALID_ARGUMENT",
  "category": "ERROR_CATEGORY_VALIDATION",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/invalid-argument",
    "title": "Invalid Argument",
    "status": 400,
    "detail": "The root_node_id parameter is required",
    "instance": "/v1/nodes"
  }
}

`ERROR_CODE_VALIDATION_FAILED` (2) - Validation Failed

HTTP Status: 422 Unprocessable Entity
gRPC Code: InvalidArgument
Category: ERROR_CATEGORY_VALIDATION
Logging: Not logged (debug level)
Slug: validation-failed

Indicates that request validation failed. This error occurs when parameters pass basic format checks but fail business logic validation rules.

Common Causes:

Field value constraints violated (e.g., string too short, number out of range)
Business rule violations
Invalid relationships between fields
Invalid state transitions

Example:

{
  "code": "ERROR_CODE_VALIDATION_FAILED",
  "category": "ERROR_CATEGORY_VALIDATION",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/validation-failed",
    "title": "Validation Failed",
    "status": 422,
    "detail": "One or more validation errors occurred",
    "validation_errors": [
      {
        "field": "namespace_id",
        "code": "REQUIRED",
        "message": "namespace_id is required",
        "constraint": "required"
      },
      {
        "field": "query",
        "code": "TOO_SHORT",
        "message": "query must be at least 1 character",
        "rejected_value": "",
        "constraint": "min_length: 1"
      }
    ]
  }
}

`ERROR_CODE_UNAUTHORIZED` (3) - Unauthorized

HTTP Status: 401 Unauthorized
gRPC Code: Unauthenticated
Category: ERROR_CATEGORY_AUTHENTICATION
Logging: Not logged (info level)
Slug: unauthorized

Indicates that authentication is required or has failed. This error occurs when the Authorization header is missing or invalid.

Common Causes:

Missing Authorization header
Invalid namespace identifier
Namespace does not exist

Example:

{
  "code": "ERROR_CODE_UNAUTHORIZED",
  "category": "ERROR_CATEGORY_AUTHENTICATION",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "The Authorization header is required",
    "instance": "/v1/nodes"
  }
}

`ERROR_CODE_FORBIDDEN` (4) - Forbidden

HTTP Status: 403 Forbidden
gRPC Code: PermissionDenied
Category: ERROR_CATEGORY_AUTHORIZATION
Logging: Logged (info level)
Slug: forbidden

Indicates that the authenticated user does not have permission to perform the requested operation.

Common Causes:

Insufficient permissions for the namespace
Operation not allowed for the current user
Resource access restrictions

Example:

{
  "code": "ERROR_CODE_FORBIDDEN",
  "category": "ERROR_CATEGORY_AUTHORIZATION",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "You do not have permission to access this resource",
    "instance": "/v1/corpus/corpus-123"
  }
}

`ERROR_CODE_NOT_FOUND` (5) - Not Found

HTTP Status: 404 Not Found
gRPC Code: NotFound
Category: ERROR_CATEGORY_CLIENT
Logging: Not logged (debug level)
Slug: not-found

Indicates that the requested resource was not found.

Common Causes:

Node identifier does not exist
Corpus identifier does not exist
Namespace identifier does not exist
Resource was deleted

Example:

{
  "code": "ERROR_CODE_NOT_FOUND",
  "category": "ERROR_CATEGORY_CLIENT",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/not-found",
    "title": "Resource Not Found",
    "status": 404,
    "detail": "Node with id '12345' not found",
    "instance": "/v1/nodes/12345"
  }
}

`ERROR_CODE_CONFLICT` (6) - Conflict

HTTP Status: 409 Conflict
gRPC Code: AlreadyExists
Category: ERROR_CATEGORY_CLIENT
Logging: Logged (info level)
Slug: conflict

Indicates that the request conflicts with the current state of the resource.

Common Causes:

Namespace already exists
Resource version conflicts
Concurrent modification conflicts

Example:

{
  "code": "ERROR_CODE_CONFLICT",
  "category": "ERROR_CATEGORY_CLIENT",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/conflict",
    "title": "Resource Conflict",
    "status": 409,
    "detail": "Namespace 'my-namespace' already exists",
    "instance": "/v1/namespaces"
  }
}

Server Errors (5xx)

`ERROR_CODE_INTERNAL` (10) - Internal Server Error

HTTP Status: 500 Internal Server Error
gRPC Code: Internal
Category: ERROR_CATEGORY_SERVER
Logging: Logged (error level)
Slug: internal-error

Indicates an unexpected internal server error. This error should not occur under normal circumstances and indicates a bug or system failure.

Common Causes:

Unexpected exceptions
System failures
Unhandled error conditions

Example:

{
  "code": "ERROR_CODE_INTERNAL",
  "category": "ERROR_CATEGORY_SERVER",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/internal-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

`ERROR_CODE_SERVICE_UNAVAILABLE` (11) - Service Unavailable

HTTP Status: 503 Service Unavailable
gRPC Code: Unavailable
Category: ERROR_CATEGORY_SERVER
Logging: Logged (warn level)
Slug: service-unavailable
Retryable: Yes

Indicates that the service is temporarily unavailable. This error is retryable and includes retry information.

Common Causes:

Service maintenance
Temporary overload
Dependency service unavailable

Example:

{
  "code": "ERROR_CODE_SERVICE_UNAVAILABLE",
  "category": "ERROR_CATEGORY_SERVER",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/service-unavailable",
    "title": "Service Unavailable",
    "status": 503,
    "detail": "The service is temporarily unavailable",
    "retry_info": {
      "retryable": true,
      "retry_after_ms": 5000,
      "max_retries": 3,
      "backoff_type": "exponential",
      "backoff_ms": 1000
    }
  }
}

`ERROR_CODE_TIMEOUT` (12) - Timeout

HTTP Status: 504 Gateway Timeout
gRPC Code: DeadlineExceeded
Category: ERROR_CATEGORY_TIMEOUT
Logging: Logged (warn level)
Slug: timeout
Retryable: Yes

Indicates that the request timed out. This error is retryable and includes retry information.

Common Causes:

Request processing exceeded timeout
Upstream service timeout
Long-running operation timeout

Example:

{
  "code": "ERROR_CODE_TIMEOUT",
  "category": "ERROR_CATEGORY_TIMEOUT",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/timeout",
    "title": "Request Timeout",
    "status": 504,
    "detail": "The request timed out after 30 seconds",
    "retry_info": {
      "retryable": true,
      "retry_after_ms": 2000,
      "max_retries": 2,
      "backoff_type": "linear",
      "backoff_ms": 1000
    }
  }
}

`ERROR_CODE_DATABASE_ERROR` (13) - Database Error

HTTP Status: 500 Internal Server Error
gRPC Code: Internal
Category: ERROR_CATEGORY_DATABASE
Logging: Logged (error level)
Slug: database-error

Indicates a database operation failed. This error indicates a problem with database connectivity or query execution.

Common Causes:

Database connection failures
Query execution errors
Transaction failures
Constraint violations

Example:

{
  "code": "ERROR_CODE_DATABASE_ERROR",
  "category": "ERROR_CATEGORY_DATABASE",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/database-error",
    "title": "Database Error",
    "status": 500,
    "detail": "Database operation failed",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

`ERROR_CODE_STORAGE_ERROR` (14) - Storage Error

HTTP Status: 500 Internal Server Error
gRPC Code: Internal
Category: ERROR_CATEGORY_STORAGE
Logging: Logged (error level)
Slug: storage-error

Indicates a storage operation failed. This error indicates a problem with blob storage or file system operations.

Common Causes:

Storage service unavailable
File upload failures
Blob retrieval failures
Storage quota exceeded

Example:

{
  "code": "ERROR_CODE_STORAGE_ERROR",
  "category": "ERROR_CATEGORY_STORAGE",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/storage-error",
    "title": "Storage Error",
    "status": 500,
    "detail": "Failed to upload file to storage",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

`ERROR_CODE_TRIGGER_EXECUTION_FAILED` (15) - Trigger Execution Failed

HTTP Status: 500 Internal Server Error
gRPC Code: Internal
Category: ERROR_CATEGORY_TRIGGER
Logging: Logged (error level)
Slug: trigger-execution-failed

Indicates that a trigger execution failed. This error occurs when an automated trigger encounters an error during execution.

Common Causes:

Trigger configuration errors
Trigger execution exceptions
Dependency failures in trigger processing

Example:

{
  "code": "ERROR_CODE_TRIGGER_EXECUTION_FAILED",
  "category": "ERROR_CATEGORY_TRIGGER",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/trigger-execution-failed",
    "title": "Trigger Execution Failed",
    "status": 500,
    "detail": "Trigger 'corpus_parsing' failed to execute",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

`ERROR_CODE_WORKFLOW_ERROR` (16) - Workflow Error

HTTP Status: 500 Internal Server Error
gRPC Code: Internal
Category: ERROR_CATEGORY_WORKFLOW
Logging: Logged (error level)
Slug: workflow-error

Indicates that a workflow execution failed. This error occurs when a workflow encounters an error during processing.

Common Causes:

Workflow activity failures
Workflow configuration errors
Workflow orchestration failures

Example:

{
  "code": "ERROR_CODE_WORKFLOW_ERROR",
  "category": "ERROR_CATEGORY_WORKFLOW",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/workflow-error",
    "title": "Workflow Error",
    "status": 500,
    "detail": "Workflow 'parsing_workflow' failed during execution",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Categories

Error categories group errors by domain for observability and monitoring:

Category	Description
`ERROR_CATEGORY_UNSPECIFIED`	Unspecified category
`ERROR_CATEGORY_CLIENT`	Client-side errors (4xx)
`ERROR_CATEGORY_SERVER`	Server-side errors (5xx)
`ERROR_CATEGORY_NETWORK`	Network-related errors
`ERROR_CATEGORY_DATABASE`	Database operation errors
`ERROR_CATEGORY_STORAGE`	Storage operation errors
`ERROR_CATEGORY_AUTHENTICATION`	Authentication errors
`ERROR_CATEGORY_AUTHORIZATION`	Authorization errors
`ERROR_CATEGORY_VALIDATION`	Validation errors
`ERROR_CATEGORY_RATE_LIMIT`	Rate limiting errors
`ERROR_CATEGORY_TIMEOUT`	Timeout errors
`ERROR_CATEGORY_WORKFLOW`	Workflow execution errors
`ERROR_CATEGORY_TRIGGER`	Trigger execution errors

Error Response Format

HTTP Response

HTTP error responses follow RFC 9457 Problem Details format:

{
  "code": "ERROR_CODE_VALIDATION_FAILED",
  "category": "ERROR_CATEGORY_VALIDATION",
  "problem_details": {
    "type": "https://api-docs.biolevatecloud.com/errors/validation-failed",
    "title": "Validation Failed",
    "status": 422,
    "detail": "One or more validation errors occurred",
    "instance": "/v1/nodes",
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-01T12:00:00Z",
    "validation_errors": [
      {
        "field": "node_id",
        "code": "REQUIRED",
        "message": "node_id is required"
      }
    ]
  },
  "service": "proxy-node",
  "operation": "GetNode",
  "should_log": false,
  "log_level": "debug"
}

gRPC Response

gRPC error responses embed MatsuError in gRPC status details. The gRPC status code is mapped from the error code, and the error details include the complete MatsuError structure.

Error Handling

Retry Logic

Errors with retryable: true in retry_info should be retried using the provided retry guidance:

Exponential Backoff: Use backoff_ms * (2 ^ retry_count) for delays
Linear Backoff: Use backoff_ms * retry_count for delays
Max Retries: Respect the max_retries limit
Retry After: Wait at least retry_after_ms before the first retry

Error Logging

Errors include logging metadata:

should_log: Whether the error should be logged
log_level: The log level to use (debug, info, warn, error)

Client errors (4xx) are typically not logged, while server errors (5xx) are logged at error or warn levels.

Trace Correlation

All errors include a trace_id that enables correlation across services. Use this identifier when reporting errors or investigating issues.

Overview​

Error Structure​

Problem Details​

Validation Errors​

Retry Information​

Error Codes​

Client Errors (4xx)​

ERROR_CODE_INVALID_ARGUMENT (1) - Invalid Argument​

ERROR_CODE_VALIDATION_FAILED (2) - Validation Failed​

ERROR_CODE_UNAUTHORIZED (3) - Unauthorized​

ERROR_CODE_FORBIDDEN (4) - Forbidden​

ERROR_CODE_NOT_FOUND (5) - Not Found​

ERROR_CODE_CONFLICT (6) - Conflict​

Server Errors (5xx)​

ERROR_CODE_INTERNAL (10) - Internal Server Error​

ERROR_CODE_SERVICE_UNAVAILABLE (11) - Service Unavailable​

ERROR_CODE_TIMEOUT (12) - Timeout​

ERROR_CODE_DATABASE_ERROR (13) - Database Error​

ERROR_CODE_STORAGE_ERROR (14) - Storage Error​

ERROR_CODE_TRIGGER_EXECUTION_FAILED (15) - Trigger Execution Failed​

ERROR_CODE_WORKFLOW_ERROR (16) - Workflow Error​

Error Categories​

Error Response Format​

HTTP Response​

gRPC Response​

Error Handling​

Retry Logic​

Error Logging​

Trace Correlation​

Overview

Error Structure

Problem Details

Validation Errors

Retry Information

Error Codes

Client Errors (4xx)

`ERROR_CODE_INVALID_ARGUMENT` (1) - Invalid Argument

`ERROR_CODE_VALIDATION_FAILED` (2) - Validation Failed

`ERROR_CODE_UNAUTHORIZED` (3) - Unauthorized

`ERROR_CODE_FORBIDDEN` (4) - Forbidden

`ERROR_CODE_NOT_FOUND` (5) - Not Found

`ERROR_CODE_CONFLICT` (6) - Conflict

Server Errors (5xx)

`ERROR_CODE_INTERNAL` (10) - Internal Server Error

`ERROR_CODE_SERVICE_UNAVAILABLE` (11) - Service Unavailable

`ERROR_CODE_TIMEOUT` (12) - Timeout

`ERROR_CODE_DATABASE_ERROR` (13) - Database Error

`ERROR_CODE_STORAGE_ERROR` (14) - Storage Error

`ERROR_CODE_TRIGGER_EXECUTION_FAILED` (15) - Trigger Execution Failed

`ERROR_CODE_WORKFLOW_ERROR` (16) - Workflow Error

Error Categories

Error Response Format

HTTP Response

gRPC Response

Error Handling

Retry Logic

Error Logging

Trace Correlation