/**
 * Standard API error response format
 * Returned by APIError.toJSON() in apps/api
 * Consumed by Command Center UI for type-safe error handling
 */
export interface APIErrorResponse {
  /** Human-readable error message */
  error: string

  /** Machine-readable error code */
  code: APIErrorCode

  /** Request ID for debugging (optional) */
  requestId?: string

  /** Field-level validation errors (only present for VALIDATION_ERROR code) */
  fields?: Record<string, string[]>

  /** Seconds until the rate limit resets (only present for RATE_LIMIT_EXCEEDED code) */
  retryAfter?: number

  /** Structured detail payload (e.g. linked-row counts on CONFLICT errors) */
  details?: Record<string, unknown>
}

/**
 * Type-safe error codes
 * MUST match API_ERROR_CODES in apps/api/src/errors/error-codes.ts
 */
export type APIErrorCode =
  | 'VALIDATION_ERROR'
  | 'AUTHENTICATION_FAILED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'CONFLICT'
  | 'RATE_LIMIT_EXCEEDED'
  | 'INTERNAL_SERVER_ERROR'
  | 'SERVICE_UNAVAILABLE'
